pkzip securezip for z/os - pkware.cachefly.net · securezip for z/os, pkzip for z/os, securezip for...
TRANSCRIPT
PKZIP®/SecureZIP® for z/OS®
User’s Guide
SZZU-V9R0022
PKWARE Inc.
PKWARE, Inc. 648 N Plankinton Avenue, Suite 220 Milwaukee, WI 53203 Main office: 888-4PKWARE (888-475-9273) Sales: 937-847-2374 (888-4PKWARE / 888-475-9273) Sales: Email: [email protected] Support: 937-847-2687 Support: http://www.pkware.com/business_and_developers/support Fax: 414-289-9789 Web Site: http://www.pkware.com 9.0 Edition (2006) SecureZIP for z/OS, PKZIP for z/OS, SecureZIP for i5/OS®, PKZIP for i5/OS, SecureZIP for UNIX, and SecureZIP for Windows are just a few of the members of the PKZIP family. PKWARE Inc. would like to thank all the individuals and companies—including our customers, resellers, distributors, and technology partners—who have helped make PKZIP the industry standard for trusted ZIP solutions. PKZIP enables our customers to efficiently and securely transmit and store information across systems of all sizes, ranging from desktops to mainframes. This edition applies to the following PKWARE Inc. licensed programs: PKZIP for z/OS (Version 9, Release 0, 2006) SecureZIP for z/OS (Version 9, Release 0, 2006) SecureZIP Partner for z/OS (Version 9, Release 0, 2006) PKWARE, PKZIP and SecureZIP are registered trademarks of PKWARE, Inc. z/OS, i5/OS, zSeries, and iSeries are registered trademarks of IBM Corporation. Other product names mentioned in this manual may be trademarks or registered trademarks of their respective companies and are hereby acknowledged. Any reference to licensed programs or other material, belonging to any company, is not intended to state or imply that such programs or material are available or may be used. The copyright in this work is owned by PKWARE Inc., and the document is issued in confidence for the purpose only for which it is supplied. It must not be reproduced in whole or in part or used for tendering purposes except under an agreement or with the consent in writing of PKWARE Inc., and then only on condition that this notice is included in any such reproduction. No information as to the contents or subject matter of this document or any part thereof either directly or indirectly arising there from shall be given or communicated in any manner whatsoever to a third party being an individual firm or company or any employee thereof without the prior consent in writing of PKWARE Inc. Copyright © 1989 - 2010 PKWARE Inc. All rights reserved.
iii
Contents
PREFACE............................................................................................................. 1
Notices.........................................................................................................................1
About this Manual.......................................................................................................1
Conventions Used in This Manual ............................................................................3
PKZIP and SecureZIP Manuals..................................................................................3
Related Publications ..................................................................................................4
Related Information on the Internet..........................................................................5
User Help and Contact Information ..........................................................................5
1 INTRODUCTION TO PKZIP AND SECUREZIP FOR Z/OS.......................... 6
Data Compression......................................................................................................7
ZIP Archives ................................................................................................................7
Cyclic Redundancy Check.........................................................................................8
Distinctive Features of PKZIP and SecureZIP for z/OS ..........................................8
Distinctive Features of SecureZIP for z/OS..............................................................9
Encryption Using Passwords and/or Digital Certificates .....................................10
Cross Platform Compatibility ..................................................................................10
2 INTRODUCTION TO DATA SECURITY ...................................................... 12
SecureZIP for z/OS Security Basics .......................................................................12 Operating System Levels........................................................................................13 Digital Certificate Formats.......................................................................................13 SecureZIP for Windows Compatibility.....................................................................13 General Information to Help You Get Started.........................................................14 How do we activate MASTER_RECIPIENT Contingency Keys? ...........................14
Encryption .................................................................................................................17
Authentication...........................................................................................................17
iv
Data Integrity...........................................................................................................18 Digital Signature Validation.....................................................................................18 Digital Signature Source Validation ........................................................................19
Public-Key Infrastructure and Digital Certificates ................................................19 Public-Key Infrastructure (PKI) ...............................................................................19 x.509 .......................................................................................................................20 Digital Certificates ...................................................................................................20 Certificate Authority (CA) ........................................................................................20 Private Key..............................................................................................................20 Public Key ...............................................................................................................21 Certificate Authority and Root Certificates..............................................................21
Setting Up Stores for Digital Certificates on zOS .................................................21 Setting Up the Certificate Stores.............................................................................21 Updating the Certificate Stores ...............................................................................23
Types of Encryption Algorithms .............................................................................23 FIPS 46-3, Data Encryption Standard (DES)..........................................................23 Triple DES Algorithm (3DES)..................................................................................24 Advanced Encryption Standard (AES)....................................................................24 Comparison of the 3DES and AES Algorithms.......................................................24 RC4 .........................................................................................................................25
Key Management ......................................................................................................25
Passwords and PINS................................................................................................26
Recipient Based Encryption....................................................................................26
Random Number Generation...................................................................................26
Integrity of Public and Private Keys .......................................................................27
3 PKZIP AND SECUREZIP FOR Z/OS RELEASE INFORMATION............... 28
Release Summary.....................................................................................................28 New Products..........................................................................................................28 New Features..........................................................................................................28 New Commands and Defaults ................................................................................31 Command Changes ................................................................................................35 Message Changes ..................................................................................................37 Enhancements for Secure Data..............................................................................37
Restrictions for PKZIP and SecureZIP for z/OS ....................................................37
Region Size and Storage..........................................................................................39
SMS Dataclass Considerations...............................................................................40 Note for users of PKZIP for MVS and PKZIP for zSeries 5.6 .................................41
Reserved DDNAMEs.................................................................................................41 SYSPRINT ..............................................................................................................42 PKSPRINT ..............................................................................................................42 PKNODUMP ...........................................................................................................42
Use of System Utilities.............................................................................................42 SORT ......................................................................................................................42 Access Method Services.........................................................................................43
v
IEBGENER..............................................................................................................43 GRS/ENQ................................................................................................................43
4 LICENSING .................................................................................................. 44
Operating Requirements..........................................................................................44 Change of Release Licensing .................................................................................44 Grace Period ...........................................................................................................44
Initializing the License .............................................................................................44
5 GETTING STARTED WITH PKZIP AND SECUREZIP ................................ 45
Introduction to PKZIP and SecureZIP for z/OS......................................................45
Invoking PKZIP/SECZIP or PKUNZIP/SECUNZIP Using JCL................................46 Return Codes ..........................................................................................................47
Compressing a Dataset............................................................................................47 Notes for Dataset Compression..............................................................................48
Viewing the Contents of an Archive .......................................................................48 Notes for Viewing the Contents of an Archive ........................................................49 ACTION(VIEWDETAIL ...........................................................................................49
Decompressing a Dataset........................................................................................50 Notes for Decompressing a Dataset .......................................................................50
Updating or Refreshing a File .................................................................................51
Invoking the PKZIP and SecureZIP for z/OS Utility...............................................51 Invoking PKZIP/SecureZIP from JCL (Batch or Started Task) ...............................51 Invoking PKZIP/SecureZIP as Called Programs Under TSO .................................51 Invoking ZIP or UNZIP TSO Command Line Interface...........................................52
Valid ZIP Actions ......................................................................................................53
Valid ZIP Options ......................................................................................................54
Valid UNZIP Actions .................................................................................................54 Invoking the PKZIP and SecureZIP for z/OS ISPF Panel Interface .......................56
Configuration Manager ............................................................................................56 Making Changes to the Defaults.............................................................................56 Assembling Your Changes .....................................................................................57 Inputs ......................................................................................................................57
Configuration Manager Processing: Managing Control Statements .................58 Control Statement Definitions .................................................................................58
Troubleshooting .......................................................................................................59 PKZIP and SecureZIP for z/OS Messages.............................................................59 Debugging Controls ................................................................................................59
6 ABOUT SECURITY, CERTIFICATES AND ENCRYPTION......................... 60
Terms and Acronyms Used in This Chapter..........................................................60
Accessing Certificates .............................................................................................61
vi
Configuration Profile ................................................................................................61 Contents of the Configuration Profile ......................................................................62 Data Base (DB) Profile (Local Certificate Store).....................................................62 LDAP Profile (Networked Certificate Store)............................................................62 Recipient Searches.................................................................................................63
Local Certificate Stores............................................................................................64 Access x.509 Public and Private Key Certificates ..................................................64 Authentication and Certificate Validation Policies...................................................65 Other Profile Commands ........................................................................................69 SecureZIP Certificate Store Administration and Configuration...............................70
Run-Time Configuration...........................................................................................70 Runtime Configuration Panel ..................................................................................70 Runtime Configuration Panel: Certificate Stores ....................................................71 SecureZIP Runtime Configuration Panel Undefined ..............................................72 SecureZIP Runtime Configuration Panel with DB Profile Defined..........................73 SecureZIP Runtime Configuration Panel with Private Certificate Location ............73
Filename Encryption ................................................................................................74 How SecureZIP for z/OS Encrypts File Names ......................................................74 When SecureZIP for z/OS Encrypts File Names ....................................................74 Encrypting File Names When You Update an Archive ...........................................74 Opening and Viewing an Archive That Has Encrypted File Names .......................75 Input Required To View Recipients in a Filename Encrypted Archive ...................75 View of Recipients in a Filename Encrypted Archive .............................................75 View Detail of an Archive that Has Encrypted File Names.....................................77 Decrypting a Filename-Encrypted Archive .............................................................78
Security Examples....................................................................................................78 SecureZip using Recipients or Combo ...................................................................78 Zip Compress File(s) to an Archive FIle (Option ‘Z’ ) Using Recipients .................79 SecureZIP Encryption Using Individual Recipients as Input...................................79 SecureZIP Certificate Report Option ......................................................................81 SecureZIP Verification Window ..............................................................................81 SecureZIP Encryption Using Individual Recipients-Generated JCL.......................81 SecureZIP Encryption Using Recipient Job Output Listing with VERBOSE...........82 SecureZIP Encryption Using Recipient Job Output Listing Without VERBOSE.....83 SecureZIP Encryption Using a Recipients List .......................................................84 Editing the Recipients List.......................................................................................84 SecureZIP Encryption Using a Recipients List .......................................................85 SecureZIP Halt Process Request ...........................................................................85 SecureZIP Encryption Using LDAP Search for Recipients.....................................86 SecureZIP Encryption Using LDAP Search for Recipients-Generated JCL...........86 SecureZIP Encryption Using LDAP Search for Recipients - Output.......................87 Selecting Filename Encryption ...............................................................................88 Panel Option “Z” - Selecting Filename Encryption..................................................88 Zip Compress File(s) to an Archive FIle (Option ‘Z’ ) Using Passwords.................88 SecureZIP Encryption .............................................................................................89 Cryptographic Algorithms........................................................................................90
UNZip File(s) from an Archive (Option ‘U’ ) Using Recipients.............................92 Unzip Panel (Option ‘U’ ) Using Recipients ............................................................92 Unzip Output Using Recipients ...............................................................................93
View Display the Contents of an Archive File (Option ‘V’ ) .................................93
vii
View Detail Display .................................................................................................94
Incorrect Password Use...........................................................................................95
7 FILE SELECTION AND NAME PROCESSING ........................................... 98
ZIP Processing File Selection .................................................................................98
Primary File Selection Inputs ..................................................................................98
Cataloged Dataset Name Filter Requests ..............................................................98
Exclusion Filters .......................................................................................................99
INFILE DD Requests .................................................................................................99
JES2 SYSIN INFILE Support....................................................................................99
Input ZIP Archive Files ...........................................................................................100
File Selection Processing Notes ...........................................................................100
Cataloged Dataset Name and INFILE Request Restrictions ..............................101
ZIP File Names ........................................................................................................102 Summary of Commands Affecting ZIP Filename..................................................102
Essentials for running PKZIP/SECZIP and PKUNZIP/SECUNZIP ......................103 PKUNZIP/SECUNZIP ...........................................................................................103
8 ZIP FILES ................................................................................................... 105
Data Formats - Text or Binary ...............................................................................105
Data Format - Text Records...................................................................................106
Data Format - Binary Records...............................................................................107
File Attributes..........................................................................................................107 Data Set Name Transformation ............................................................................108
Large File Considerations .....................................................................................108
Determining File Size .............................................................................................109
9 FILE PROCESSING ................................................................................... 110
File Support.............................................................................................................110
Sequential Files ......................................................................................................111 Compressing Sequential Files ..............................................................................111 Extracting Records into a Sequential File.............................................................112 Managing a Sequential File ZIP Archive...............................................................112 Processing GDGs .................................................................................................113 File Concatenation for ZIP Processing .................................................................113
PDS and PDSE Members .......................................................................................113 Selecting PDS Members for Compression ...........................................................113 Extracting Data into a PDS ...................................................................................114 Managing ZIP Archives as PDS Members ...........................................................114 Load Libraries .......................................................................................................115
viii
VSAM Files ..............................................................................................................115 Compressing a VSAM File....................................................................................116 Extracting Data into a VSAM File..........................................................................117 Managing a VSAM ZIP Archive ............................................................................119
Magnetic Tapes and Cartridges ............................................................................119 Copying a Tape-Based Archive to a Disk File ......................................................119 Compressing Data from Tape...............................................................................120 Extracting Data onto Tape ....................................................................................121 Managing a ZIP Archive on Tape .........................................................................121
10 COMMANDS .............................................................................................. 125
Command Syntax ...................................................................................................125
File Selections vs. Commands..............................................................................126 &SYSUID ..............................................................................................................126
Summary of Available Commands .......................................................................126
Command Details ...................................................................................................142 Command Icon Legend.........................................................................................144
11 ZIP ARCHIVES........................................................................................... 292
“Old” ZIP Archive ...................................................................................................293
“Temporary” Dataset..............................................................................................293
“New” ZIP Archive ..................................................................................................294
12 PROCESSING WITH GZIP ........................................................................ 295
What Is GZIP? .........................................................................................................295
Why Use GZIP? .......................................................................................................295
PKZIP and SecureZIP for z/OS Implementation Notes for GZIP ........................296 GZIP Restrictions ..................................................................................................296 GZIP Extensions ...................................................................................................296 Processing GZIP Archives ....................................................................................297
13 USING THE ISPF INTERFACE.................................................................. 298
Getting Started with the ISPF Interface ................................................................298
Configuration (Option ‘C’)......................................................................................299
Defaults (Options ZD and UD) ...............................................................................300 Primary Commands ..............................................................................................301 Changing Default Options.....................................................................................302 Including Changed Defaults..................................................................................302
View Archive (Option ‘V’) .......................................................................................302 Setting VIEW Options ...........................................................................................303 Primary Commands ..............................................................................................305 Line Commands....................................................................................................306 Display Fields........................................................................................................307
ix
Using Security .......................................................................................................309 Archive Authenticated ...........................................................................................309 File Signers ...........................................................................................................310
Zip (Option ‘Z’) ........................................................................................................311 Using Security .......................................................................................................313 Select Password Protect.......................................................................................314 Select Recipients ..................................................................................................314 Archive Signing .....................................................................................................315 File Signing ...........................................................................................................315 Archive Authentication ..........................................................................................316
UNZIP (Option ‘U’) ..................................................................................................316 Using Security .......................................................................................................318 Select Password Protect.......................................................................................318 Select Recipients ..................................................................................................319 Archive Authentication ..........................................................................................319 File Authentication.................................................................................................320
SYSPRINT Browse (Option ‘S’) .............................................................................320
Messages (Option ‘M’)............................................................................................321
License Display (Option ‘L’) ..................................................................................322
Certificate Stores (Option ‘CS’).............................................................................323
What’s New (Option ‘W’) ........................................................................................323
Contact PKWARE (Option ‘A’)...............................................................................323
14 USER API PROCESSING .......................................................................... 324
Overview..................................................................................................................324 Data Record Transformation API for ZIP processing. ..........................................324 File Name Manipulation API for UNZIP processing..............................................324
Invocation................................................................................................................324 Negation of API processing ..................................................................................325 Execution Environment .........................................................................................325 File Name Manipulation API .................................................................................326 Data Record Transformation API..........................................................................326
User API Samples ...................................................................................................327
JCL and Sample Programs....................................................................................327 Assembler .............................................................................................................327 Assembler Source.................................................................................................327 Assembler JCL......................................................................................................328 Assembler Source.................................................................................................328 DCTMAPIU DSECT ..............................................................................................329 COBOL..................................................................................................................329 COBOL JCL ..........................................................................................................329 COBMAPIU copy member ....................................................................................330 Sample input file - SAMPDAPI..............................................................................330
Output from sample jobs .......................................................................................331 ASMFNAPI Sample Output...................................................................................331 XSMFNAPI Sample Output...................................................................................331
x
User API_Module Program Exception Trap..........................................................332
15 INVOKING PKZIP/PKUNZIP FROM AN APPLICATION PROGRAM....... 334
CALLZIPA Sample Assembly Source to Call PKZIP ...........................................335
CALLZIPC Sample COBOL Source to Call PKZIP ...............................................337
CALLZIPP Sample PL/I Source to Call PKZIP......................................................338
CALLZIPR Sample REXX Source to Call PKZIP ..................................................339
CALLZC Sample C source program to call PKZIP ..............................................340
CALLZCPP Sample C++ program source to call PKZIP .....................................341
16 PKWARE PARTNERLINK: SECUREZIP PARTNER ................................ 344
About SecureZIP Partner for z/OS ........................................................................344 If You Are a Sponsor: Sign the Central Directory .................................................345
Terms and Acronyms Used in This Chapter........................................................345
PKWARE PartnerLink Program: Overview...........................................................346 Decrypting and Extracting Sponsor Data (Read Mode)........................................346 Creating an Archive for a Sponsor........................................................................347
Requirements..........................................................................................................347 License..................................................................................................................347 Operating Environment .........................................................................................347 Sponsoring Configuration .....................................................................................347
Functional Overview...............................................................................................347 General Restrictions..............................................................................................348
SecureZIP Partner (Read mode) Processing .......................................................348 Restrictions ...........................................................................................................348 Archive Authentication Settings ............................................................................349 Decryption Certificate Selection............................................................................349 File Signature Authentication Certificate Selection...............................................349
SecureZIP Partner (Write mode) Processing.......................................................349 Restrictions ...........................................................................................................350 Encryption Certificate Selection ............................................................................351 Archive Authentication Settings ............................................................................351
A (RESERVED).............................................................................................. 352
B SAMPLE JOBSTREAMS ........................................................................... 353
Example 1: Zip PDS to an Archive .......................................................................353
Example 2: Zip PDS to an Archive .......................................................................354
Example 3: Zip VSAM KSDS to an Archive.........................................................355
Example 4: Summary View of a Dataset..............................................................356
Example 5: Summary View of a Dataset..............................................................357
xi
Example 6: View with Detail of an Archive..........................................................358
Example 7: Unzip an Archive to PDS...................................................................360
Example 8: Unzip an Archive to PDS...................................................................360
Example 9: Unzip an Archive to VSAM KSDS ....................................................361
C 3490 INSTALLATION JCL (COPYCART) ................................................. 363
D MAKING CODE PAGE TRANSLATE TABLES (EDCICONV) .................. 373
Translation Tables ..................................................................................................373
Code Page Support ................................................................................................373
International Code Page Support..........................................................................374
Code Conversion Utility.........................................................................................374
Translate Table Generation ...................................................................................375
Sample Job..............................................................................................................375
E FIPS-197 AES CERTIFICATION OF PKZIP AND SECUREZIP................ 377
F CONTACT INFORMATION ........................................................................ 378
PROBLEM REPORTING .........................................................................................378 General .................................................................................................................378 Licensing ...............................................................................................................379 ISPF ......................................................................................................................379 FTP SERVER requirements .................................................................................380
GLOSSARY...................................................................................................... 381
INDEX............................................................................................................... 389
xii
1
Preface
This manual covers both PKZIP for z/OS and SecureZIP for z/OS.
PKZIP for z/OS provides powerful, easy-to-use data compression on the mainframe. PKZIP for z/OS Enterprise Edition additionally includes support for password-based decryption of encrypted files, powered by trusted RSA® BSAFE. Files created by PKZIP for z/OS use the widely-adopted ZIP format and can be accessed on all major platforms throughout the enterprise—from mainframe to PC.
SecureZIP for z/OS provides powerful, easy-to-use data compression and data protection on the mainframe. SecureZIP for z/OS delivers high performance data compression and protects data with digital signatures and trusted RSA BSAFE encryption, either password- or certificate-based, with key lengths of up to 256 bits. Like PKZIP for z/OS, SecureZIP for z/OS uses the widely-adopted ZIP format and creates files that can be accessed on all major platforms throughout the enterprise.
Notices
To better align our products with IBM naming conventions and to support the future development of new products on the IBM System z and System i platforms, PKWARE has changed the names of its large-platform products to reference the compatible IBM operating systems instead of specific platforms. In particular, beginning with version 9.0, the PKZIP product is called PKZIP for z/OS instead of PKZIP for zSeries, as in version 8.x, and SecureZIP is called SecureZIP for z/OS instead of SecureZIP for zSeries.
Licensing requirements have changed for this release. See Chapter 4 for details.
About this Manual
This manual provides the information needed to use PKZIP/SecureZIP for z/OS in an operational environment. It is assumed that anyone using this manual has a good understanding of JCL and data set processing. This manual applies to the following operating systems:
OS/390 – Version 2.10.
z/OS - all releases.
2
Chapter 1. An introduction to both PKZIP/SecureZIP for z/OS. Provides a general description of the product suite applicable to all supported platforms. This chapter also describes the features of the PKZIP/SecureZIP for z/OS products and provides a simple description of how it is used to compress and decompress datasets.
Chapter 2. Provides a general discussion on data security along with specific implementations of encryption.
Chapter 3. Provides more detailed examples of how specific file types should be processed by PKZIP/SecureZIP for z/OS. This chapter also details the new features and functions introduced in various releases.
Chapter 4. This chapter explains licensing of PKZIP/SecureZIP for z/OS and provides information on invoking the 5-day grace period and disaster recovery tests.
Chapter 5. Provides general information on invoking PKZIP/SECZIP and PKUNZIP/SECUNZIP, the main component programs of PKZIP/SecureZIP for z/OS. This chapter explains the details associated with compression, decompression, restrictions, migration, and an overview of ZIP processing.
Chapter 6. Provides details on security and authentication, including ISPF screen images and examples.
Chapter 7. Provides a summary of ZIP file processing procedures, including filtering, file selection, requests, and the basic essentials for running the ZIP and UNZIP programs.
Chapter 8. Explains ZIP file formats (text or binary), files attributes, and file size considerations.
Chapter 9. Provides information about the types of files that are supported by PKZIP/SecureZIP for z/OS, such as sequential files, PDS, or PDSE members, and VSAM files.
Chapter 10. A reference covering the PKZIP/SecureZIP for z/OS commands and messages.
Chapter 11. Explains the possible states of an archive during processing and the functions of associated formats.
Chapter 12. Provides an overview of how to process GZIP files and archives, including information about GZIP restrictions and extensions.
Chapter 13. Provides instructions on the use of other facilities provided with PKZIP/SecureZIP for z/OS, specifically the ISPF panel interface, to include setting options for configuration, defaults, and viewing archives.
Chapter 14. Provides information on the User Application Programming Interface or USER API.
Chapter 15. Provides information on calling PKZIP/SECZIP and PKUNZIP/SECUNZIP.
Chapter 16. Provides information about the PKWARE PartnerLink program
Appendix B. Sample Jobstreams
Appendix C. 3490 Installation JCL
Appendix D. Making Code Page Translate Tables
3
Appendix E. FIPS-197 AES Certification
Appendix F. Contact Information
Glossary. Explains terms related to compression and encryption
Conventions Used in This Manual
Throughout this manual, the following conventions are used:
PKZIPz (bold-italicized) refers to both PKZIP for z/OS and SecureZIP for z/OS. Information given for PKZIPz applies to both products. Information given specifically for PKZIP for z/OS or SecureZIP for z/OS applies specifically to that product.
The use of the Courier font indicates text that may be found in job control language (JCL), parameter controls, or printed output.
The use of italics in a command line indicates a value that must be substituted by the user, for example, a data set name. Italics are also used in body text to quote command names and so forth or to indicate the title of a manual or other publication.
Bullets (•) indicate items (or instructions) in a list.
The use of <angle brackets> in a command definition indicates a mandatory parameter.
The use of [square brackets] in a command definition indicates an optional parameter.
A vertical bar (|) in a command definition is used to separate mutually exclusive parameter options or modifiers.
When sample JCL is shown, or references to the PKZIPz libraries are made, the high-level qualifier PKWARE.MVS may be used generically. The high-level qualifiers for the packaged products are PKZIP.MVS for PKZIP for z/OS and SECZIP.MVS for SecureZIP for z/OS). Also, please note that the actual high-level qualifiers installed on your system may be different.
Program examples may show either SecureZIP or PKZIP constructs. In general, examples apply to both programs unless the examples appear in sections of the manual that relate exclusively to SecureZIP features. Such sections are marked like this:
Requires SecureZIP
PKZIP and SecureZIP Manuals
PKZIP for Series and SecureZIP for z/OS product manuals include:
PKZIP/SecureZIP for z/OS User’s Guide - Provides detailed information on the product set in OS/390 and z/OS operating environments. Provides a general introduction to data compression, PKZIP-specific data compression, and an overview of how to use PKZIPz control cards, and parameters. Provides SecureZIP-specific security extension information.
4
PKZIP/SecureZIP for z/OS Messages and Codes Guide - Provides information on the messages and codes that are displayed on the consoles, printed outputs, and associated terminals.
PKZIP/SecureZIP for z/OS System Administrator’s Guide - Provides detailed information to assist the system administrator to install and manage PKZIPz in an operational environment. Topics include:
o System planning and administration
o Installation, licensing and configuration
o Verifying the installation
o Security administration overview (SecureZIP)
o Certificate store management (SecureZIP)
Related Publications
IBM Manuals relating to the PKZIPz products include:
System Codes - Documents the completion codes issued by the operating system when it terminates a task or an address space. Describes the wait state codes placed in the program status word (PSW) when the system begins a wait state. Describes the causes of loops.
System Messages - Documents the messages issued by the OS/390 operating system. The descriptions explain why the component issued the message, give the actions of the operating system, and suggest responses by the applications programmer, system programmer, and/or operator.
JES2 Messages - Documents the messages issued by the JES2 subsystem. The descriptions explain why the component issued the message, give the actions of the operating system, and suggest responses by the applications programmer, system programmer, and/or operator.
JCL User's Guide - Describes the job control tasks needed to enter jobs into the operating system, control the system's processing of jobs, and request the resources needed to run jobs. To perform the tasks, programmers code job control statements. The user's guide assists in deciding how to perform job control tasks.
JCL Reference - Describes the job control tasks needed to enter jobs into the operating system, control the system's processing of jobs, and request the resources needed to run jobs. To perform the tasks, programmers code job control statements. The reference guide; is designed to be used while coding the statements.
Access Methods Services - Documents the functions that are available with Virtual Storage Access Method (VSAM) and describes the IDCAMS commands that can be issued to control VSAM datasets.
TSO/E Command Reference - Documents the functions of the TRANSMIT and RECEIVE Command Facility used for the distribution and allocation of PKZIPz installation libraries.
5
ICSF Application Programmers Guide – Describes how to use the callable services provided by the Integrated Cryptographic Service facility.
ICSF Administrators Guide – Describes how to manage cryptographic keys by using the zOS Integrated Cryptographic Service facility.
ICSF Overview – Contains overview and planning information for the zOS Integrated Cryptographic Service facility.
MVS/QuickRef 6.3 (Chicago-Soft, Ltd.) - Includes both messages and command reference material for PKZIPz.
Related Information on the Internet
PKWARE, Inc.
www.pkware.com
FTP site
Product manuals - ftp://bigiron.pkware.com/pub/manuals/zOS
Product downloads - ftp://bigiron.pkware.com/pub/products
o PKZIP for z/OS - ftp://bigiron.pkware.com/pub/products/pkzip/zOS
o SecureZIP for z/OS - ftp://bigiron.pkware.com/pub/products/securezip/zOS
o PartnerLink: SecureZIP Partner -ftp://bigiron.pkware.com/pub/products/partnerlink/zOS
National Institutes of Standards and Technology
Computer Security Resource Center - http://csrc.ncsl.nist.gov
Information on the AES development - http://csrc.nist.gov/encryption/aes/
Information on Key Management - http://csrc.nist.gov/CryptoToolkit/tkkeymgmt.html
RSA BSAFE® Content Library – http://www.rsasecurity.com/content_library.asp
User Help and Contact Information
For licensing, please contact Sales at 937-847-2374 (888-4PKWARE / 888-475-9273) or email [email protected].
For technical assistance, contact Technical Support at 937-847-2687 or visit the support web site: http://www.pkware.com/business_and_developers/support
Appendix F lists the types of information needed to resolve issues with the product.
6
1 Introduction to PKZIP and SecureZIP for z/OS
Built on the award-winning PKZIP, SecureZIP for z/OS enables you to create and extract ZIP archives and archives of other types and, with the new security features, to use passwords and/or digital certificates to strongly encrypt archives and archived files. Strong, digital certificate-based encryption enables you to encrypt files just for the people you want to see them.
With its advanced password and certificate-based security features, SecureZIP for z/OS offers multiple methods of encryption and is an excellent choice for secure messaging and storage. Like PKZIP, SecureZIP for z/OS offers various methods and levels of compression and a host of other powerful features.
PKZIP for z/OS and SecureZIP for z/OS each come in two editions: a Standard Edition and an Enterprise Edition that provides additional features:
PKZIP for z/OS Standard Edition provides compression and all basic functionality for creating and working with archives.
PKZIP for z/OS Enterprise Edition adds the ability to decrypt strong, password-based encryption applied to archives by SecureZIP.
SecureZIP for z/OS Standard Edition provides the ability to apply strong, password-based encryption to archives.
SecureZIP for z/OS Enterprise Edition adds the ability to use digital certificates to apply digital signatures and strong, certificate-based encryption to archives.
SecureZIP for z/OS Enterprise Edition also enables you to access certificates stored in LDAP certificate stores on remote directory servers. This extends your ability to work with certificates that belong to your colleagues in the enterprise as well as customers, partners, and vendors. SecureZIP can automatically search the remote stores for certificates belonging to your email recipients for whom you want to encrypt attachments.
PKZIPz contains two main programs: PKZIP (or SECZIP in SecureZIP) and PKUNZIP (or SECUNZIP in SecureZIP). The ZIP program compresses or otherwise stores files into a ZIP format archive; the UNZIP program extracts files compressed into ZIP-compatible archives. Processing control is available through the use of customized option modules, shared command lists, and individual job inputs. In addition to file selection, features such as compression levels and performance selections can be specified.
7
SecureZIP for z/OS is also available in a special version—SecureZIP Partner—through the PKWARE PartnerLink program. The PKWARE PartnerLink program provides a straightforward, secure way for an organization to exchange sensitive information with outside partners who perhaps do not have SecureZIP.
SecureZIP Partner differs from the full SecureZIP for z/OS in that it only extracts archives from, and only creates and encrypts archives for, a PartnerLink sponsor. Contact PKWARE for more information on PKWARE PartnerLink.
To guarantee data integrity, 32-bit Cyclic Redundancy Check (CRC) is a standard feature for all products.
A ZIP archive is platform-independent; therefore, data compressed (zipped) on one platform, such as UNIX or Windows, can be decompressed (unzipped) on another platform, such as OS/390 or z/OS by using a compatible version of the UNZIP program.
Data Compression
Data compression reduces file size. A compressed data file uses less storage space and can be transferred faster. A data file to be compressed (a ZIP candidate) is compressed to a compact size (ZIPPED file). To use the file again, it must be uncompressed or extracted to its original size (UNZIPPED file).
For example, a simple data compression technique is the Run-Length Encoding method. This method works when repeating characters are evident in a data stream. The run of characters is represented in a compressed form as a single character with its count.
Example: B 2 2 2 2 E H H H H H H H H H
Compressed: B *4 2 E H*9
However, to perform a thorough compression operation, more advanced algorithms and enhanced techniques are required which work at the bit level and allow for noncontiguous iterations of bit strings. PKZIPz uses such methods to achieve maximum results.
ZIP Archives
PKZIPz stores compressed data files into ZIP archives. There is no limit to the number of archives you may create.
A ZIP archive refers to any valid ZIP-format file created by a ZIP-compatible product.
PKWARE's Application Note on the .ZIP file format provides developers a general description and technical details of the ZIP specification. This specification is periodically revised according to the publication policy statement as new features are added to ensure the continued interoperability of ZIP applications.
With the ZIP64 feature available in SecureZIP for z/OS and PKZIP for z/OS (Enterprise Edition) release 5.6 and higher, over 4 billion files can be managed within a single archive. The ZIP archive architecture supports Exabyte (64-bit) sizes for files in an archive. ZIP archives themselves can exceed 4 gigabytes for specified access methods and device media.
8
With ZIP products prior to release 4.5 (and PKZIP for MVS products), an archive can store up to 65,535 files. File sizes of less than 4 gigabytes in size can be compressed, and an archive is limited to less than 4 gigabytes in size.
For each file in an archive, the following information is stored with the compressed data:
Filename
File directory date and time
File’s initial CRC value. See Cyclic Redundancy Check
Method of compression used
ZIP Version required for file extraction
File size, uncompressed
File size, compressed
Some files may contain the following additional information:
The version of ZIP that created the file
File attributes
A comment about the file
A comment about the archive
Platform specific attributes (see Cross Platform Compatibility)
Cyclic Redundancy Check
A Cyclic Redundancy Check (CRC) is performed to check the integrity of a data file when it is restored from a ZIP archive.
While a file is compressed, a PKZIPz algorithm computes a 32-bit hexadecimal value for its data. That CRC value is stored with the file in the ZIP archive. When the data in the file is extracted, PKZIPz processes it again by the same algorithm to produce a second CRC value and compares the two. If the data has not changed, the values will be the same. If the two CRC values do not match, data may have been corrupted in the ZIP archive during file transfer operations, and PKZIPz reports the failure.
Distinctive Features of PKZIP and SecureZIP for z/OS
Distinctive features of SecureZIP for the z/OS and OS/390 operating environments include:
Ability to process execution from ISPF Panels, as a TSO/E command, within TSO/E REXX EXECs or CLISTs, from an application program, or a stand-alone batch utility.
A robust ISPF panel interface that displays the ZIP archive directory in a table format and enables selection of individual archived (zipped) files for browsing, viewing, extracting, or deleting.
Compression and extraction of datasets of the following types on DASD:
Sequential files.
9
PDS and PDSE members.
VSAM files (KSDS, ESDS, RRDS).
JES2 subsystem input files (for example, //ddname DD *).
Command extensions allowing greater flexibility in file selection.
Unique filename translation to/from system/390 DSNAME conventions and the UNIX-style names typically found in zip archives.
Compressing and extracting of datasets of the following types on tape or cartridge:
Sequential files.
Compressing and extracting of files to OS/390 and z/OS Load Libraries.
Compressing and extracting of files to Generation Data Groups (GDGs).
GDG files can be used as a ZIP archive.
Retention of dataset allocation information, such as dataset organization, device type, and DCB/Cluster attributes. Preservation of this information allows for duplication of the file with the same characteristics during the UNZIP process. Support of ZIP archives within the following dataset organizations:
Sequential files (DASD, Tape, or Cartridge).
PDS and PDSE members.
VSAM ESDS.
Selection of datasets for processing based upon user-specified control statements, DD JCL specifications, or user-defined filtering lists.
Execution on OS/390 2.10. SecureZIP also executes on a z/OS system IPL’d in 64-bit mode.
Execution in AMODE 31, using storage primarily above the 16-Mb line. However, certain operating system control blocks and system services require virtual storage below the 16-Mb line. The amount of virtual storage available within each of these areas of an address space will limit the use of some performance options (for example, multi-tasking and temporary files in storage) and capabilities.
Defaults customizable during installation. Multiple defaults modules may be created for use in a variety of application needs.
Use of pre-defined command files saved in a place selected by the user or system administrator. These can be referenced by multiple jobs or users, thus eliminating the need for individual JCL command streams, or used in combination with individual job inputs to provide a consistent set of processing controls.
Certain features of PKZIP for z/OS are separately licensed (see Chapter 4).
Distinctive Features of SecureZIP for z/OS
Distinctive features of SecureZIP for the z/OS and OS/390 operating environments include:
10
Incorporation of the IBM Integrated Cryptographic Service Facility (ICSF) APIs, enabling the use of hardware acceleration on a variety of hardware platforms for data encryption/decryption and digital signature creation/authentication.
The ability to access certificates in directory servers through an LDAP-compliant interface. SecureZIP can look for certificates in LDAP certificate stores and automatically search these stores for recipients to whom you are sending an email message so that you can use their keys when encrypting an attachment.
Certain features of SecureZIP for z/OS are separately licensed (see Chapter 4).
Encryption Using Passwords and/or Digital Certificates
Requires SecureZIP
SecureZIP for z/OS can encrypt data for security control with digital certificates and/or provide a password lockout for extracting data. Varying security levels are available with multiple encryption algorithms. See Chapter 2 for a complete description of security features in SecureZIP for z/OS.
Cross Platform Compatibility
PKZIPz was designed for cross-platform use and enables you to move data among different computer operating environments. Archives created with PKZIP/SecureZIP for z/OS are compatible with, PKZIP for MVS, PKZIP/SecureZIP for i5/OS, PKZIP for OS/400, PKZIP/SecureZIP for UNIX, PKZIP/SecureZIP for LINUX, PKZIP for DOS, and PKZIP/SecureZIP for Windows. All of these products use the the same ZIP archive file format and can work with each other’s archives. As a result, data can be zipped on one platform—for example, UNIX—and unzipped onto another platform, such as OS/400. PKZIPz automatically converts the data between EBCDIC and ASCII, so files prepared on the host are readable on any PC or UNIX system.
The following table lists ZIP features supported on different platforms and the version of the ZIP file format Application Note where the features appear. In the table, (EE) refers to PKZIP for z/OS Enterprise Edition.
11
ZIP Feature ZIP AppNote Version MVS/ z/OS OS400/iSeries
Default 1.0
File represents a volume label
1.1 Not supported Not supported
File represents a folder 2.0 Not supported Not supported
Deflate compression 2.0 2.x 2.x
Traditional encryption 2.0 2.x 2.x
Deflate64 compression 2.1 8.2 8.2
DCL Implode compression 2.5 Not supported Not supported
File is a patched data set 2.7 Not supported Not supported
File uses ZIP64 size extensions
4.5 5.6 5.6
BZip2 compression 4.6 Not supported Not supported
DES encryption 5.0 8.2 8.2
3DES encryption 5.0 8.2 8.2
RC2 encryption 5.0 Not supported Not supported
RC4 encryption 5.0 8.2 8.2
AES encryption 5.1 5.5 5.5
DES decryption 5.0 SZ8.2, PK8.2(EE) SZ8.2, PK8.2(EE)
3DES decryption 5.0 SZ8.2, PK8.2(EE) SZ8.2, PK8.2(EE)
RC4 decryption 5.0 SZ8.2, PK8.2(EE) SZ8.2, PK8.2(EE)
AES decryption 5.1 SZ5.5, PK8.2(EE) SZ5.5, PK8.2(EE)
Certificate encryption using non-OAEP key wrapping
6.1 8.2 (SecureZIP) 8.2 (SecureZIP)
Central directory encryption (file name encryption)
6.2 8.2 (SecureZIP) 8.2 (SecureZIP)
If you want to transfer data across platforms using any other “ZIP compatible” product, you should check with the supplier first to confirm which versions of PKZIP it is compatible with.
12
2 Introduction to Data Security
In this chapter we will detail how SecureZIP for z/OS can strongly encrypt data for security control and protection. Much of the reference information in this chapter is from the National Institutes of Standards and Technology. The NIST Computer Security Resource Center web site, http://csrc.ncsl.nist.gov/, contains FAQs and documentation relating to computer security along with the Federal Information Processing Standard (FIPS) documents. The PKWARE web site, www.pkware.com, also contains information relating to security and links to the RSA Security, Inc., Web site that provides detailed information on the BSAFE® implementation used in SecureZIP for z/OS.
The following sections describe encryption, types of algorithms: in use, information about specific mandates requiring the use of secure data, and how SecureZIP for z/OS secures that data. Examples are provided in Chapter 6.
See Chapter 10 for documentation for the commands.
Note: PKZIP for z/OS provides support for password-based encryption and decryption using a 96-bit “Standard” encryption algorithm that is supported by older ZIP-compatible utilities. PKZIP for z/OS Enterprise Edition supports the decryption of all password-based algorithms provided in SecureZIP for z/OS.
SecureZIP for z/OS Security Basics
SecureZIP for z/OS security functions include strong encryption tools using RSA BSAFE and IBM ICSF cryptographic services. SecureZIP for z/OS provides the option for data encryption using RC4, DES, 3DES and AES (key lengths of 128, 192, or 256 bits).
SecureZIP for z/OS uses a multi-layer key generation process, based on a user-specified password of up to 250 characters, and/or a users digital certificate, that creates a unique internal key for each file being processed. The same password will result in a different system-generated key for each file.
SecureZIP for z/OS also implements Cipher Block Chaining (CBC) to further enhance industry standard encryption algorithms. This feature ensures that each block of data is uniquely modified, further protecting the data from fraudulent access.
SecureZIP for z/OS encryption is activated through the use of the PASSWORD and RECIPIENT commands. If a value is present for either setting, whether through commands or default settings, then encryption will be attempted in accordance with other settings (for
13
example, ENCRYPTION_METHOD). However, if ENCRYPTION_METHOD=NONE is specified, then encryption will be bypassed.
Archives created under PKZIP for Windows and PKZIP for UNIX using the encryption setting Strong: Recipient List or Password can be decrypted with the password on z/OS systems running release 8.0 or later.
SecureZIP for z/OS signing and authentication features are activated through the use of the SIGN_ARCHIVE, SIGN_FILES and AUTHCHK commands.
Operating System Levels OS/390 2.10 or any zOS release is required to run certificate-based operations. If your operating system is not at this level, you will receive the message, ZPEN100E Certificate-Based functions require a minimum operating system…. You will receive a RC=12.
Digital Certificate Formats
Requires SecureZIP
SecureZIP for z/OS requires that X.509 certificates be used and that they conform to specific formats depending on the type being accessed or administered. See the section “Setting Up Stores for Digital Certificates on zOS,” later in this chapter, for more information.
SecureZIP for Windows Compatibility Windows users running pre-XP versions of Windows may experience a problem decrypting depending on the way in which private-key certificates are imported on the system. Unless the dialog check box “Mark the private key as exportable” is selected when certificates are imported on pre-XP Windows, Windows will allow an AES encrypted file to be decrypted only if the master session key is wrapped with 3DES.
A new command, Secure_OPT_MSK3DES, is introduced with RECIPIENT processing which allows the SecureZip user to create AES-encrypted files that are compatible with older Windows workstations. When turned on, the MSK3DES flag is set in the NDH/DIB, indicating that the master session key information is protected with 3DES when recipients are specified.
PKZIP for Windows has a variance in processing for versions 6.0 and 7.x because of an issue with OAEP encryption processing. PKZIP for Windows 5.0 through 6.0 used OAEP. However, OAEP was found to be incompatible with smart cards, so versions 6.1 and later set a NO_OAEP flag in the NDH/DIB flags and no longer create OAEP encryption-mode files by default.
SecureZIP for z/OS always sets NO_OAEP; therefore, PKZIP for Windows 5.0 - 6.0 will not be able to read recipient-list encrypted files from the large platforms.
SecureZIP for z/OS should be able to detect whether the NO_OAEP flag is set and successfully extract in either case. No change in logic is required within the SecureZIP high-level code, but the low-level EVTCERTD code should handle the switch based on the flag.
14
General Information to Help You Get Started
How do I activate encryption in SecureZIP for z/OS? Encryption is activated through the use of the PASSWORD (and/or RECIPIENT for SecureZIP) commands. If a value is present for either setting, whether through commands or default settings, then encryption will be attempted in accordance with other settings (such as ENCRYPTION_METHOD). However, if ENCRYPTION_METHOD=NONE is specified, then encryption will be bypassed.
Note that certificate-based encryption for recipients is only supported by SecureZIP, not by PKZIP versions of the product. Also, this mode of encryption requires that one of the strong encryption methods (minimum 128-bit) be selected.
How do we activate MASTER_RECIPIENT Contingency Keys? To meet the needs of corporate security policies, SecureZIP provides the ability to use the MASTER_RECIPIENT setting to include one or more master recipient contingency key certificate files in a SecureZIP job when an ENCRYPTION_METHOD specification other than “STANDARD” is activated. The setting causes the data to be encrypted for the master recipient(s) in addition to other recipient or password settings, thereby ensuring that the organization can always decrypt its encrypted data.
The primary MASTER_RECIPIENT may be set directly in the defaults module, or indirectly by specifying MASTER_RECIPIENT in a command stream referenced by SECUREZIP_CONFIG. This default-module-only setting specifies a PDS[E] member that contains SecureZIP certificate store configuration commands to be automatically included in the processing stream. The configuration command values from this member are included at the start of command input processing, before //SYSIN statements are read. The data set(member) is internally converted into an "INCLUDE_CMD=(pds[e](member)" command and is echoed to the message log in accordance with the ECHO setting. The primary MASTER_RECIPIENT is reported in the SHOW_SETTINGS report.
Supplemental MASTER_RECIPIENT commands may be provided via the primary SYSIN input stream or indirectly from either the SECUREZIP_CONFIG or INCLUDE_CMD specifications. They will be internally converted to RECIPIENT commands for processing.
MASTER_RECIPIENT settings are cumulative. Therefore a setting in the defaults module is not overridden or eliminated from an execution.
How does the MASTER_RECIPIENT contingency key setting affect processing? When SecureZIP is used to encrypt data, either with RECIPIENT or PASSWORD (exclusive of ENCRYPTION_METHOD=STANDARD), then a recipient specified by MASTER_RECIPIENT will be automatically included. However, MASTER_RECIPIENT does not trigger encryption.
How does recipient-based encryption differ from password? Password-based encryption depends on both the sender and receiver knowing, and providing input (the password), in clear text. The password is used to derive a binary master session key for each decryption run. No key information is kept within the ZIP archive, therefore both parties must retain the password in an external location.
15
Recipient-based encryption provides a means by which the master session key (MSK) information can be hidden, protected, and carried within the ZIP archive. This is done by using technique known as digital enveloping with public key encryption. The technique requires that the creating process have a copy of the recipient's public key digital certificate, which is used to protect and store the MSK. The receiving side must have a copy of the recipient's private key digital certificate. With these two pieces of information in place, there is no need for users to retain or recall a password for decryption.
What is a Digital Certificate Store?
Requires SecureZIP
Recipient-based encryption requires that public and private key certificates be used by SecureZip for z/OS. These are kept in file streams encoded according to the X.509 standard. A certificate store is the location of where various types of certificates are kept and accessed.
The primary stores used by SecureZip for z/OS include:
CSPUB: Certificate store for individual public-key X.509 certificates on the local system.
CSPRVT: Certificate store for individual private-key X.509 certificates on the local system.
CSCA: Certificate store for certificate authority public-key X.509 certificates on the local system.
CSROOT: Certificate store for the trusted root public-key X.509 certificates on the local system.
LDAP: Certificate store for individual public-key X.509 certificates accessible via a TCPIP network.
Can both recipient-based and password encryption be used together? Yes. When both RECIPIENT and PASSWORD settings are used, to encrypt a file, the master session key is derived from the password and is also protected by using public key encryption. This means that the file can be decrypted either by supplying the password or by providing access to a private key associated with a public key used to encrypt.
How does ENCRYPTION_METHOD pertain to recipient or password encryption? Public/private key encryption using BSAFE digitally envelopes the master session key information. Once the master session key is determined, an independent file session key is derived (which is unique for each file) to encrypt the file data with a symmetric algorithm specified by ENCRYPTION_METHOD. Several algorithms are supplied with SecureZip for z/OS. Any algorithm may be specified for use with a password, but only those prefixed with “BSAFE” are valid for use with recipient-based encryption.
Which encryption settings should I choose? Various external factors such as legislative requirements or corporate policy may influence your selection an algorithm or mode of encryption. However, in general, certificate-based encryption is considered more secure than password-based encryption.
16
Except for the older 96-bit “Standard” SecureZip for z/OS encryption algorithm, encryption algorithms are provided at a minimum of 128 bits.
PKWARE supports interoperability among OS/390, zOS, OS400, iSeries, UNIX and Windows for all algorithms provided with ENCRYPTION_METHOD for PKWARE products at release 8.0 and later. Older releases of PKWARE products support “Standard” 96-bit encryption.
When RECIPIENT PKI exchanges are required, then ENCRYPTION_METHOD must specify an algorithm whose name begins with “BSAFE”.
Password-based AES encryption is supported by PKWARE products at release 5.5 or higher.
BSAFE_AES and AES password-based encryption are 100% compatible. Archives created with PKZIP for zSeries Release 5.5 can be bi-directionally exchanged with SecureZip or PKZIP products using the BSAFE AES algorithms.
The BSAFE algorithms provided for the OS/390 and z/OS products are high-performance algorithms. The 128-bit BSAFE algorithms out-perform the older 96-bit PKZIP “Standard” algorithm.
How many recipients can be specified? The ZIP file format specification allows for a maximum list size of 3,275 recipients. This can be restricted further by other file attributes associated with the data and by run-time capacity limitations (such as virtual storage). (Approximately 20 bytes are required for each recipient within the ZIP archive central directory record for each file. This area is limited to 64K in size).
What are digital signatures? A digital signature is an unforgeable mechanism that ensures that the file to which it is attached originates from the owner of the signature and is unchanged since it was signed. The private key from a user’s digital certificate is used to attach a digital signature. The signature is authenticated by application of the public key from the certificate.
Files in a ZIP archive can be digitally signed, and an archive itself can be digitally signed. An archive is signed by attaching a signature to its central directory, which contains archive meta-data, including the list of files in the archive.
A signed ZIP archive can contain files that are signed or unsigned (or both). Signing an archive enables people who receive it to confirm that the archive as a whole is not changed. Signing only files in an archive enables people to confirm that the individual signed files are unchanged but does not guarantee that files have not been added or removed.
SecureZIP for Windows can use certificates to sign files and to authenticate digital signatures on files that you receive from others.
SecureZIP for z/OS provides an informational message that a ZIP archive central directory signature exists. SecureZIP for z/OS prevents a ZIP archive from being altered in-place when its central directory is signed.
What is file name encryption? Someone who cannot decrypt the contents of an archive may still be able to infer sensitive information just from the unencrypted names of files. To prevent this, you can encrypt the names of files in addition to their contents. Encrypted file names can be viewed in the clear—that is, unencrypted—only when the archive is opened by an intended recipient, if the archive
17
was encrypted using a recipient list, or by someone who has the password, if the archive was encrypted using a password.
SecureZip for z/OS encrypts file names using your current settings for (strong) encryption method and algorithm. File names can be encrypted using either strong password encryption or a recipient list (or both). You must use one of the strong encryption methods: you cannot encrypt file names using traditional encryption.
Encrypting names of files and folders in an archive encrypts and hides a good deal of other internal information about the archive as well. To encrypt file names, SecureZip for z/OS encrypts the archive's central directory, where virtually all such metadata about the archive is stored. Be aware, however, that archive comments are not encrypted even when you encrypt file names. Do not put sensitive information in an archive comment.
An archive that contains encrypted file names requires PKZIP for zSeries 8.x, SecureZIP for zSeries 8.x, or PKZIP/SecureZIP for z/OS to open it. These versions of SecureZIP can use passwords, recipients, or a combination of the two to do filename encryption. With these versions of PKZIP, only passwords can be used to do filename encryption.
Encryption
Encryption provides confidentiality for data. Unencrypted data is called plaintext. Encryption transforms the plaintext data into an unreadable form, called ciphertext, using an encryption key. Decryption transforms the ciphertext back into plaintext using a decryption key.
Several algorithms have been approved in FIPS for the encryption of general purpose data. Each of these algorithms is a symmetric key algorithm, where the encryption key is the same as the decryption key. SecureZIP for z/OS uses symmetric key algorithms when encrypting user data.
In order to maintain the confidentiality of the data encrypted by a key, the key must be known only by the entities that are authorized to access the data. These symmetric key algorithms are commonly known as block cipher algorithms because the encryption and decryption processes each operate on blocks (chunks) of data of a fixed size.
FIPS 46-3 and FIPS 197 have been approved for the encryption of general-purpose data. The protection of keys is discussed below under “Key Management.”
Authentication
Requires SecureZIP
Authentication is the process of validating digital signatures that may be attached to files in an archive or to an archive’s central directory.
Authentication is a separate operation from data encryption. Whereas encryption is concerned with preventing parties from accessing sensitive data (such as private medical or financial information), authentication confirms that information actually comes unchanged from the purported source.
Authenticating digitally signed data both verifies the signature and validates the signed data.
18
Data Integrity Both PKZIP and SecureZIP use a Cyclic Redundancy Check (CRC) to ensure that data is successfully transferred into and out of a ZIP archive. The CRC process creates a unique hash value “thumbprint” from the original data stream. The thumbprint is regenerated at the receiving end and compared with the hash of the source for equality. The thumbprint value is stored independently of the data stream and is used during UNZIP processing to complete validation of the data.
SecureZIP extends the concept of the CRC in two ways for the purpose of providing a tamper-resistant container within the ZIP archive. First, more rigorous HASH algorithms (MD5 and SHA-1) are used (as specified by the SIGN_HASHALG command) in addition to the 32-bit CRC to accurately reflect the uniqueness of the data stream. Second, the hash value is encrypted within a digital signature using a private-key certificate for the purpose of tamper detection at the completion of file extraction.
For more information regarding SHA-1 (Secure Hash Algorithm), see FIPS PUB 180-1, describing the Secure Hash Standard, at http://www.itl.nist.gov/fipspubs/fip180-1.htm.
SecureZIP for z/OS provides two commands, SIGN_ARCHIVE and SIGN_FILES, to intiate the creation of digital signatures within the ZIP archive. The AUTHCHK command is used to perform a tamper check operation using the digital signature and hash.
Digital Signature Validation
Requires SecureZIP
SecureZIP makes use of certificate-based encryption within the public key infrastructure (PKI) to generate and validate digital signatures. PKI provides an authentication chain for certificates to guarantee that the signature was created by the purported source. SecureZIP supports the certificate chain authentication process by including necessary identification information within the ZIP archive. Subsequently, the certificate(s) used for signing can be authenticated through a complete chain of trust.
To complete the chain of trust, a root (or self-signed) certificate representing the certificate’s issuing organization is installed on the authenticating system. This provides the receiving organization with the authority to declare how the final trust sequence should be treated. Signatures based on certificates from certificate authorities (CA) that are not authorized or trusted are declared as being untrusted by SecureZIP.
Additional facets of validating a certificate’s viability for use include a defined range of dates within which a certificate may be used and whether the certificate has been declared to have been revoked. Configurable SecureZIP policies (EXPIRED and REVOKED attributes) provide support to ensure that the certificates involved in authentication also adhere to these restrictions.
SecureZIP for z/OS provides a means to install and access the certificates necessary for signing and authentication. The AUTHCHK command, along with configured policy settings governs the type (archive directory or data files) and level of authentication that is to be performed.
19
Digital Signature Source Validation A final step in completing the authentication process is to ensure that the archive and/or file data was sent from a particular source. Up to this point, using the previous two aspects of authentication, we are certain that the archive directory and/or files were signed with a private-key certificate that came from a trusted source (CA) and that the data stream has not been tampered with since it was placed into the ZIP archive. However, these steps alone do not guarantee that a different party under the same root/CA chain did not perform the signing operation.
SecureZIP for z/OS provides an optional parameter in the AUTHCHK command to declare the specific party from whom the data is expected.
Public-Key Infrastructure and Digital Certificates
Public-Key Infrastructure (PKI) Use of digital certificates for encryption and digital signing relies on a combination of supporting elements known as a public-key infrastructure (PKI). These elements include software applications such as SecureZIP that work with certificates and keys as well as underlying technologies and services.
The heart of PKI is a mechanism by which two cryptographic keys associated with a piece of data called a certificate are used for encryption/decryption and for digital signing and authentication. The keys look like long character strings but represent very large numbers. One of the keys is private and must be kept secure so that only its owner can use it. The other is a public key that may be freely distributed for anyone to use to encrypt data intended for the owner of the certificate or to authenticate signatures.
How the Keys Are Used With encryption/decryption, a copy of the public key is used to encrypt data such that only the possessor of the private key can decrypt it. Thus anyone with the public key can encrypt for a recipient, and only the targeted recipient has the key with which to decrypt.
With digital signing and authentication, the owner of the certificate uses the private key to sign data, and anyone with access to a copy of the certificate containing the public key can authenticate the signature and be assured that the signed data really proceeds unchanged from the signer.
Authentication has one additional step. As an assurance that the signer is who he says he is—that the certificate with Bob’s name on it is not fraudulent—the signer’s certificate itself is signed by an issuing certificate authority (CA). The CA in effect vouches that Bob is who he says he is. The CA signature is authenticated using the public key of the CA certificate used. This CA certificate too may be signed, but at some point the trust chain stops with a self-signed root CA certificate that is simply trusted. The PKI provides for these several layers of end-user public key certificates, intermediate CA certificates, and root certificates, as well as for users’ private keys.
20
x.509 X.509 is an International Telecommunication Union (ITU-T) standard for PKI. X.509 specifies, among other things, standard formats for public-key certificates. A public-key certificate consists of the public portion of an asymmetric cryptographic key (the public key), together with identity information, such as a person’s name, all signed by a certificate authority. The CA essentially guarantees that the public key belongs to the named entity.
Digital Certificates A digital certificate is a special message that contains a public key and identify information, such as the owner’s name and perhaps email address, about the owner. An ordinary, end-user digital certificate is digitally signed by the CA that issued it to warrant that the CA issued the certificate and has received satisfactory documentation that the owner of the certificate is who he says he is. This warrant, from a trusted CA, enables the certificate to be used to support digital signing and authentication, and encryption of data uniquely for the owner of a certificate.
For example, Web servers frequently use digital certificates to authenticate the server to a user and create an encrypted communications session to protect transmitted secret information such as Personal Identification Numbers (PINs) and passwords.
Similarly, an email message may be digitally signed, enabling the recipient of the message to authenticate its authorship and that it was not altered during transmission.
To use PKI technology in SecureZIP for z/OS for encryption and to attach digital signatures, you must have a digital certificate. To learn how to get a digital certificate and to use certificates for encryption, see Chapter 6.
Certificate Authority (CA) A certificate authority (CA) is a company (usually) that, for a fee, will issue a public-key certificate. The CA signs the certificate to warrant that the CA issued the certificate and has received satisfactory documentation that the owner of the new certificate is who he says he is.
Private Key A digital certificate contains both private and public portions of an asymmetric cryptographic key together with identity information, such as a person's name and (possibly) email address. The private portion of the key is called the private key and is used to decrypt data encrypted with the associated public key and to attach digital signatures.
A private key must be accessible solely by the owner of the certificate because it represents that person and provides access to encrypted data intended only for the owner.
SecureZIP for z/OS uses a private key maintained in x.509 PKCS#12 format. This means that the private key cannot be accessed unless a password is entered for each SecureZIP request.
21
Public Key A public key consists of the public portion of an asymmetric cryptographic key in a certificate that also contains identity information, such as the certificate owner’s name.
The public key is used to authenticate digital signatures created with the private key and to encrypt files for the owner of the key’s certificate.
For information on the digital enveloping process SecureZIP for z/OS uses for certificate-based encryption, download the Secure .ZIP Envelopes white paper from the PKWARE Web site.
Certificate Authority and Root Certificates End entity certificates and their related keys are used for signing and authentication. They are created at the end of the trust hierarchy of certificate authorities. Each certificate is signed by its CA issuer and is identified in the “Issued By” field in the end certificate. In turn, a CA certificate can also be issued by a higher level CA. Such certificates are known as intermediate CA certificates. At the top of the issuing chain is a self-signed certificate known as the root.
SecureZIP for z/OS uses public-key certificates in PKCS#7 format. The intermediate CA certificates are maintained independently from the ROOT certificates.
Setting Up Stores for Digital Certificates on zOS
Requires SecureZIP
To use certificates for encryption/decryption or digital signing/authentication, SecureZIP needs to access the keys in the certificates.
Unlike Windows, zOS does not have a native facility for storing digital certificates and converting them into a form that SecureZIP can use. To address this, SecureZIP provides a utility program to set up and manage certificate stores on zOS for use with SecureZIP.
Setting Up the Certificate Stores The PKWARE utility used to administer the local certificate store is accessed through an ISPF dialog. The CREATE option assists you in setting up the store and imports certificates you want SecureZIP to use. For detailed instructions on creating certificate stores on zOS, refer to the SecureZIP for z/OS System Administrator’s Guide.
The utility procedure maintains the stores listed in the following table.
22
Store Description
Public
A store for end-entity certificates used to identify encryption recipients or for authentication of digital signatures. Certificate files in this store contain only public keys; they do not contain private keys. SecureZIP for z/OS represents these certificates held in the local certificate store through the ISPF interface as “CER” entries. Other system types may refer to this store as “Other People” or “Address Book”
Private A store for end-entity certificate files with their respective private keys. Private keys are used to decrypt files or perform digital signing. SecureZIP for z/OS represents these certificates held in the local certificate store through the ISPF interface as “PFX” entries.
(Private keys in the this store are encrypted using PKCS#8 format and PKCS#5 version 2.)
Other system types may refer to this store as “Personal” or “MY Store”
Intermediate Certificate Authority
A store of issuing certificates files associated with the end-entity certificates. These certificates are used to authenticate the validity of an end-entity digital signature on a receiving system. They are also included in a SecureZIP archive when a signing operation is performed.
Other system types may refer to this store as “CA”
Trusted Root Certificate Authority
A store of issuing certificates that are classified as “self signed,” meaning that each one is at the top of a hierarchy of issuing CAs. These certificates are used to authenticate the validity of an end-entity digital signature on a receiving system. They are deemed to be “trusted” by virtue of their installation on an authenticating system. They are also included in a SecureZIP archive when a signing operation is performed.
Other system types may refer to this store as “ROOT”
The local certificate store administrative utility sets up the certificate stores as physical files containing X.509 certificates, with a VSAM index structure providing search and selection capabilities.
A SecureZIP for z/OS “create” dialog is provided to lead a systems administrator through the steps needed to allocate and prime a new local certificate store. Sample test certificates are installed to each store type, making it ready for use. In addition, a configuration file is generated that should be made accessible for SecureZIP users for use in encryption, decryption, signing, and authentication requests. The configuration file may be included explicity through an INCLUDE_CMD command, or implicitly by activating it through the PARMLIB configuration of the SecureZP defaults module.
A set of high-level qualifiers is used to control the allocation of the physical store data sets and index components. This permits multiple distinct local certificate stores to be created, administered and accessed independently within a system. This is useful for segregating test from production, or other departmental separation. Data set protection may then be applied to various components to control update or read access as needed.
RACF ALTER authority (or equivalent) must be granted to the systems administrator responsible for creating a new certificate store. This authority is also required for creating
23
backups, performing recovery operations, or performing some synchronization tasks which re-allocate components.
Updating the Certificate Stores X.509 certificates may be added to the local certificate store through the SecureZIP local certificate store administration tool. These certificates are frequently obtained through another platform and transferred (binary) to the operational zOS system for installation.
Important: All X.509 certificates should be transferred to the local zOS environment in binary mode with no translation.
When certificates are added, the certificate administration tool determines the appropriate store location based on the certificate type specified and dynamically builds an index entry for future search and selection.
SecureZIP can import certificates and keys in the following file formats:
Format Description
PEM Contains a single end-entity public-key certificate. It may be in Base-64 encoded (ascii text with ascii headers) or DER-encoded binary format.
Common file extensions: .pem, .cer, .key
PKCS#12 Contains a single end-entity private-key certificate (which also contains and its public keys). By definition, it is in binary format.
Common file extensions: .pfx, .p12
PKCS#7 Contains one or more CA (and or Root) certificates
Common file extension: .p7b
You must tell the certificate store administrative dialog what certificate file-type and key-type to import. The utility copies the existing certificates and keys from their specified location and adds them to the appropriate store locations. When transferring certificates to the zOS environment in preparation for an import to the local certificate store, be sure to allocate the file they are stored in as sequential, with a DCB RECFM of F, FB, V or VB.
RACF UPDATE authority (or equivalent) must be granted to the systems administrator responsible for altering the certificate store. This authority is also required when performing the on-line Synchronize function.
Types of Encryption Algorithms
FIPS 46-3, Data Encryption Standard (DES) The FIPS (Federal Information Processing Standards) specification 46-3 formerly specified the DES algorithm for use in Federal government applications. In 2004, the specification was changed such that DES is no longer approved for Federal government applications.
24
Triple DES Algorithm (3DES) Triple DES is a more recent algorithm related to DES. Triple DES is a method for encrypting data in 64-bit blocks using three 56-bit keys by combining three successive invocations of the DES algorithm.
ANSI X9.52 specifies seven modes of operation for 3DES and three keying options: 1) the three keys may be identical (one key 3DES), 2) the first and third key may be the same but different from the second key (two key 3DES), or 3) all three keys may be different (three key 3DES). One key 3DES is equivalent to DES under the same key; therefore, one key 3DES, like DES, will not be approved after 2004. Two key 3DES provides more security than one key 3DES (or DES), and three key 3DES achieves the highest level of security for 3DES. NIST recommends the use of three different 56-bit keys in Triple DES for Federal Government sensitive/unclassified applications.
SecureZIP for z/OS uses three-key 3DES when Triple DES is selected as the data encryption algorithm.
Advanced Encryption Standard (AES) The Advanced Encryption Standard (AES) encryption algorithm specified in FIPS 197 is the result of a multiyear, worldwide competition to develop a replacement algorithm for DES. The winning algorithm (originally known as Rijndael) was announced in 2000 and adopted in FIPS 197 in 2001.
The AES algorithm encrypts and decrypts data in 128-bit blocks, with three possible key sizes: 128, 192, or 256 bits. The nomenclature for the AES algorithm for the different key sizes is AES-x, where x is the size of the AES key. NIST considers all three AES key sizes adequate for Federal Government sensitive/unclassified applications.
Please see http://www.nist.gov/public_affairs/releases/g00-176.htm a press release recapping NIST’s position
SecureZIP for z/OS uses AES as the default encryption algorithm.
Comparison of the 3DES and AES Algorithms Both the 3DES and AES algorithms are considered to be secure for the foreseeable future. Below are some points of comparison:
3DES builds on DES implementations and is readily available in many cryptographic products and protocols. The AES algorithm is new; although many implementers are quickly adding the algorithm to their products, and protocols are being modified to incorporate the algorithm, it may be several years before the AES algorithm is as pervasive as 3DES.
The AES algorithm was designed to provide better performance (e.g., faster speed) than 3DES.
Although the security of block cipher algorithms is difficult to quantify, the AES algorithm, at any of the key sizes, appears to provide greater security than 3DES. In particular, the best attack known against AES-128 is to try every possible 128-bit key (i.e., perform an exhaustive key search, also known as a brute force attack)). By contrast, although three key 3DES has a 168-bit key, there is a “shortcut” attack on
25
3DES that is comparable, in the number of required operations, to performing an exhaustive key search on 112-bit keys. However, unlike exhaustive key search, this shortcut attack requires a lot of memory. Assuming that such shortcut attacks are not discovered for the AES algorithm, the uses of the AES algorithm may be more appropriate for the protection of high-risk or long-term data.
The smallest AES key size is 128 bits; the recommended key size for 3DES is 168 bits. The smaller key size means that fewer resources are needed for the generation, exchange, and storage of key bits.
The AES block size is 128 bits; the 3DES block size is 64 bits. For some constrained environments, the smaller block size may be preferred; however, the larger AES block size is more suitable for cryptographic applications, especially those requiring data authentication on large amounts of data.
See http://www.nist.gov/public_affairs/releases/g00-176.htm for a press release describing NIST’s position on the two algorithms.
With a block cipher algorithm, the same plaintext block will always encrypt to the same ciphertext block whenever the same key is used. If the multiple blocks in a typical message were to be encrypted separately, an adversary could easily substitute individual blocks, possibly without detection. Furthermore, data patterns in the plaintext would be apparent in the ciphertext. Cryptographic modes of operation have been defined to alleviate these problems by combining the basic cryptographic algorithm with a feedback of the information derived from the cryptographic operation.
FIPS 81, DES Modes of Operation, defines four confidentiality (encryption) modes for the DES algorithm specified in FIPS 46-3: the Electronic Codebook (ECB) mode, the Cipher Block Chaining (CBC) mode, the Cipher Feedback (CFB) mode, and the Output Feedback (OFB) mode.
SecureZIP for z/OS uses Cipher Block Chaining for data encryption.
RC4 The RC4 algorithm is a stream cipher designed by Rivest for RSA Security. It is a variable key-size stream cipher with byte-oriented operations. The algorithm is based on the use of a random permutation. Analysis shows that the period of the cipher is overwhelmingly likely to be greater than 10100. Eight to sixteen machine operations are required per output byte, and the cipher can be expected to run very quickly in software. Independent analysts have scrutinized the algorithm and it is considered secure.
RC4 is used for secure communications, as in the encryption of traffic to and from secure web sites using the SSL protocol.
Key Management
The proper management of cryptographic keys is essential to the effective use of cryptography for security. Keys are like the combination of a safe. If the combination becomes known to an adversary, the strongest safe provides no security against penetration. Similarly, poor key management can easily compromise strong algorithms. Ultimately, the security of information protected by cryptography directly depends on the strength of the keys, the effectiveness of mechanisms and protocols associated with keys, and the protection afforded the keys.
26
Cryptography can be rendered ineffective by the use of weak products, inappropriate algorithm pairing, poor physical security, and the use of weak protocols. All keys need to be protected against modification, and secret and private keys need to be protected against unauthorized disclosure. Key management provides the foundation for the secure generation, storage, distribution, and destruction of keys.
Further information is available on key management at the NIST Computer Security Resource Center web site, http://csrc.nist.gov/CryptoToolkit/tkkeymgmt.html
Passwords and PINS
FIPS 112, Password Usage, provides guidance on the generation and management of passwords used to authenticate the identity of a system user and, in some instances, to grant or deny access to private or shared data. This standard recognizes that passwords are widely used in computer systems and networks for these purposes, although passwords are not the only method of personal authentication, and the standard does not endorse the use of passwords as the best method.
The password used to encrypt a file with PKZIPz may be from 1 to 250 characters in length. Different passwords may be used for various files within a ZIP archive, although only one password may be specified per run.
The password is not stored in the ZIP archive and, as a result, care must be taken to keep passwords secure and accessible by some other source.
Recipient Based Encryption
Requires SecureZIP
Password-based encryption depends on both the sender and receiver knowing, and providing intellectual input (the password) in clear text. The password is used to derive a binary master session key for each decryption run. No key information is kept within the ZIP archive, therefore both parties must retain the password in an external location.
Recipient-based encryption provides a means by which the master session key (MSK) information can be hidden, protected, and carried within the ZIP archive. This is done by using a technique known as digital enveloping with public key encryption. The technique requires that the creating process have a copy of the recipient's public key digital certificate, which is used to protect and store the MSK. In addition, the receiving side must have a copy of the recipient's private key digital certificate. With these two pieces of information in place, there is no need for users to retain or recall a password for decryption.
Random Number Generation
Random numbers are used within many cryptographic applications, such as the generation of keys and other cryptographic values, the generation of digital signatures, and challenge response protocols. Some approved algorithms to produce random numbers have been
27
specified in FIPS 186-2, Digital Signature Standard. An effort is in progress by the Financial Services Committee of ANSI to develop a random number generation standard.
Integrity of Public and Private Keys
Public and private keys must be managed properly to ensure their integrity. The key owner is responsible for protecting private keys. The private signature key must be kept under the sole control of the owner to prevent its misuse. The integrity of the public key, by contrast, is established through a digital certificate issued by a certification authority (CA) that cryptographically binds the individual’s identity to his or her public key. Binding the individual’s identity to the public key enables the key to be reliably used, for example, to authenticate signatures created with the corresponding private key.
A PKI includes the ability to recover from situations where an individual’s private signature key is lost, stolen, compromised, or destroyed. This is done by revoking the digital certificate that contains the private signature key’s corresponding public key (discussed further below). The user then creates or is issued a new public/private signature key pair and receives a new digital certificate for the new public key.
28
3 PKZIP and SecureZIP for z/OS Release Information
Release Summary
New Products Version 9.0 adds the following products to the PKWARE SecureZIP suite for the z/OS operating environment:
SecureZIP Partner for z/OS
New Features New features in SecureZIP for z/OS Release 9.0 include:
Integrated use of IBM ICSF Cryptographic Services for improved performance in encryption, decryption, digital signing and authentication capabilities
New FACILITY_ENCRYPTDATA command
New FACILITY_HASH command
New FACILITY_RANDOM command
Hardware accelerated encryption/decryption
Hardware accelerated hashing for digital signing and authentication
New ARCHIVE_ZIPFORMAT command
New Large Block Interface tape archive handling
High performance single-stage tape processing
New features in PKZIP for z/OS Release 9.0 include:
Enhanced Tape Processing – Large Block Interface for ZIP archives on cartridge media.
Enhanced Tape Processing – Single-stage ZIP processing to cartridge media with a reduction in elapsed time and temporary work space requirements.
29
Enhanced Tape Processing – High-speed archive access on cartridge media with a reduction in elapsed time and work space requirements.
New features in SecureZIP for zSeries Release 8.2 include:
Increased passphrase (PASSWORD) length to 250 characters
Support for multiple MASTER_RECIPIENT encryption contingency keys
Faster compression
Better compression ratios
New COMPRESSION_METHOD command
New GZIPCRC_IGNORE command
New ZIP_UNMOVABLE_CHKPT command
Additional COMPRESSION_LEVEL settings
Add PKSUPPRC(ZPEN016W) License warning override
Add PKSUPPRC(ZPEX084E) Unsupported Compression method
New features in PKZIP for zSeries Release 8.2 include:
Increased pass phrase (PASSWORD) length to 250 characters
Faster compression
Better compression ratios
New COMPRESSION_METHOD command
New GZIPCRC_IGNORE command
New ZIP_UNMOVABLE_CHKPT command
Additional COMPRESSION_LEVEL settings
Add PKSUPPRC(ZPEN016W) License warning override
Add PKSUPPRC(ZPEX084E) Unsupported Compression method
New SIGNAL_ZIP64 command (Enterprise Edition)
Decryption of password-based Strongly Encrypted files (Enterprise Edition)
Decryption of password-based Strongly Encrypted Directory (Enterprise Edition)
New features in SecureZIP for zSeries Release 8.1 include:
Advanced signing and authentication security features. SecureZIP for zSeries offers the ability to digitally sign the archive directory and/or files for secure messaging and storage.
New SIGN_ARCHIVE command
New SIGN_FILES command
New AUTCHK command
30
New return code = 6 for authentication failures
Add PKSUPPRC(ZPEN035E) Archive Authentication Failure
Add PKSUPPRC(ZPEN045E) File Authentication Failure
Add PKSUPPRC(ZPEN039E) Archive Authentication Incomplete
Add PKSUPPRC(ZPEN049E) File Authentication Incomplete
Add PKSUPPRC(ZPEN057W) Certificate Validation Failed
New SIGNAL_ZIP64 command
New features in SecureZIP for zSeries Release 8.0 include:
Advanced password and certificate-based security features. SecureZIP for zSeries offers multiple methods of encryption and is an excellent choice for secure messaging and storage.
Access certificates in directory servers via an LDAP compliant interface. SecureZIP for zSeries can look for certificates in LDAP certificate stores. SecureZIP for zSeries can automatically search these stores for recipients to whom you are sending an email message so that you can use their keys when encrypting an attachment. Requires the optional Directory Integration Module.
BSAFE® Encryption
Add PKSUPPRC(ZPEN002W) Algorithm not supported by this release.
Add PKSUPPRC(ZPEN020W) FILENAME_ENCRYPTION has been deactivated in the output archive
New features introduced with PKZIP for zSeries Release 5.6:
ZIP64 Large File Support (licensed feature) to:
o Compress files > 4 gigabytes in size
o Compress up to 4 billion files (previously 65,535)
o Handle filenames up to 1,024 characters (previously 256)
o Allow for archives > 4 gigabytes in size
o Provide faster archive directory search processing
Virtual Storage Constraint Relief by reducing file management control block sizes.
A new User API for UNZIP file name transformation - allowing users to generate their own MVS names from UNIX-based file names. This feature utilizes the new FILENAME_API suite of commands
A new User API for ZIP Data Record transformation - allowing users to filter records and convert binary numeric data to clear text display numerics prior to compression. This feature utilizes the new DATA_TRANS_API suite of commands
Add INCLUDE_CMD command that assists the user in converting EBCDIC records into the correct TEXT format for a different platform target.
31
Add INCLUDE_SFX command that adds a self-extracting program to the beginning of the archive for extraction on specified releases of AIX, HP/UX, LINUX, Sun Solaris or Windows.
A new summary processing report at the end of each invocation.
Add FILENAME_SELECT_CASE command to control case-insensitivity for UNZIP filename selection.
Add LICENSE_WTO_INFO control switch to support automation traps for license expiration events.
Add ARCHIVE_MULTIVOL, OUTFILE_MULTIVOL and TEMP_SPACE_MULTIVOL commands to support extended multi-volume allocation support for archives, output files and work files.
Add PKSUPPRC(ZPCM032W) to suppress RC=4 when cataloged files are not found to be compressed.
New features introduced with PKZIP for MVS Release 5.5:
Advanced encryption (password-based, using the AES encryption algorithm)
Improved compression
Enhanced FILE FILTERING CAPABILITIES
PASSWORD echo masking
Add ACTION(COPY)
Add CHECK_SYSIN_MEMBER command
Add ENCRYPTION_METHOD command
Add EXCLUDE command
Add KEY_PROTECT_LEVEL command
Add PKSUPPRC command
Add PRESERVE_CMD_SPACE command
Rebuilt Messages manual
DOC memory usage info
DOC Abend S213-30 (IEC143I) when competing with UNZIP to PDS
PANVALET subsystem support for command input
New Commands and Defaults The following commands or their default values were introduced in the specified release.
32
Release Command Description Values
9.0 FACILITY_ENCRYPTDATA Specify the type of symmetric data encryption facilities to use
User-selectable
9.0 FACILITY_HASH Specify the type of digital signature facilities to use
User-selectable
9.0 FACILITY_RANDOM Specify the type of pseudo random data generation facilities to use
User-selectable
9.0 ARCHIVE_ZIPFORMAT Specify new tape blocksize and enhanced performance tape archive formats.
FULL
FULL_LBI
GZIP
XTAPE
XTAPE_LBI
9.0 GZIP GZIP=Y Acts a synonym for ARCHIVE_ZIPFORMAT=GZIP
GZIP=N Acts a synonym for ARCHIVE_ZIPFORMAT=FULL
8.2 COMPRESSION_LEVEL Specify a relative “strength” of compression. Additional values.
User-selectable
8.2 COMPRESSION_METHOD Specify which compression algorithm to use during ZIP.
DEFLATE32
DEFLATE64
8.2 GZIPCRC_IGNORE Yes/No switch permitting UNZIP processing for GZIP archive that has superfluous data at the end of the stream due to environmental transfer
User-selectable
8.2 PASSWORD Increased PASSWORD size 250
8.1 AUTHCHK Perform an authentication check against a signed archive directory or files
User-selectable
8.1 PKSUPPRC(ZPEN035E) Archive authentication failed User-selectable
8.1 PKSUPPRC(ZPEN039E) Archive authentication unsuccessful
User-selectable
8.1 PKSUPPRC(ZPEN045E) File authentication failed User-selectable
8.1 PKSUPPRC(ZPEN049E) File authentication unsuccessful User-selectable
8.1 PKSUPPRC(ZPEN057W) Certificate Validation Failed User-selectable
8.1 SIGN_ARCHIVE Sign the archive central directory User-selectable
8.1 SIGN_FILES Sign files added to the archive User-selectable
8.1 SIGN_HASHALG Specify digital signature hash algorithm
User-selectable
8.1 SIGNAL_ZIP64 Provides control over the creation of archives using ZIP64 extensions
User-selectable
8.1 TRANSLATE_TABLE_DATA Load module containing translation tables for EBCDIC/ASCII Text data
EBC#8859
33
Release Command Description Values
conversion.
8.1 TRANSLATE_TABLE_FILEINFO Load module containing translation tables for EBCDIC/ASCII File name and password conversion.
EBC#8859
8.0 ENCRYPT_CERT_LIMIT Restricts the number of certificates used for each encrypted file
User-supplied
8.0 FILENAME_ENCRYPTION Specifies whether the archive central directory is to be strongly encrypted
Y|N|blank)
8.0 LDAP_ENCRYPT_CERT_SELECT Restricts the number or type of certificates used in encrypting a file.
User-supplied
8.0 MASTER_RECIPIENT This enables an enterprise to decrypt and access the file(s) when other RECIPIENTs are no longer able or eligible.
User-supplied
8.0 PKSUPPRC(ZPEN002W) Algorithm not supported for this release.
User-selectable
8.0 PKSUPPRC(ZPEN020W) FILENAME_ENCRYPTION has been deactivated in the output archive
User-selectable
8.0 RECIPIENT Identifies the eligible party that may decrypt the file(s)
User-supplied
8.0 SECUREZIP_CONFIG Specifies a member that contains the cert store configuration commands to be included during processing
User-supplied
The following commands were introduced in the 5.x releases.
Release Command Description Values
5.6 ARCHIVE_FASTSEEK Performance improvement for archive read access.
Y|N
5.6 ARCHIVE_SPACE_MULTIVOL Control multi-volume allocation of the archive data set.
Y|N
5.6 DATA_TRANS_API_ERRLIM Unused at this time 0
5.6 DATA_TRANS_API_ERROR Intended action when a user API program error occurs.
STOPRUN, IGNORE, ABEND
5.6 DATA_TRANS_API_LANGUAGE Programming language/linkage used for the DATA_TRANS_API user program.
ASM, COBOL
5.6 DATA_TRANS_API_NAME Load module name of User program used to modify data records during PKZIP/SECZIP processing.
User-supplied
5.6 DATA_TRANS_API_PARM Data string to be passed to the User-supplied
34
Release Command Description Values
User API program.
5.6 DATA_TRANS_API_TRACE Tracing level for API operation. 0 – 4
5.6 DATA_TRANS_API_WORKSIZE Size of persistent work area provided by PKZIP/SECZIP to the user program.
4096
5.6 FILENAME_API_ERRLIM Unused at this time 0
5.6 FILENAME_API_ERROR Intended action when a user API program error occurs.
STOPRUN, IGNORE, ABEND
5.6 FILENAME_API_LANGUAGE Programming language/linkage used for the FILENAME_API user program.
ASM, COBOL
5.6 FILENAME_API_NAME Load module name of User program used to convert archive file names to MVS Data Set names during EXTRACT processing.
User-supplied
5.6 FILENAME_API_PARM Data string to be passed to the User API program.
User-supplied
5.6 FILENAME_API_TRACE Tracing level for API operation. 0 – 4
5.6 FILENAME_API_WORKSIZE Size of persistent work area provided by SECUNZIP to the user program.
4096
5.6 FILENAME_SELECT_CASE Affect archive filename selection case sensitivity.
M (mixed)
U (upper)
5.6 INCLUDE_CMD Include batched commands from a partitioned library.
User-supplied member
5.6 INCLUDE_SFX Create a self-extracting archive SFXAIX SFXWIN SFXHP SFXSUN SFXLNX2I
5.6 LICENSE_WTO_INFO Support console message automation for expiring license. (Specify in the defaults module).
Y|N
5.6 NOAPI The Language Environment CEEPIPI environment associated with User API programs (such as DATA_TRANS_API) will not be initialized.
User-supplied
5.6 OUTFILE_SPACE_MULTIVOL Control multi-volume allocation of an Output data set during EXTRACT.
Y|N
5.6 PKSUPPRC(ZPCM032W) Override the default RC=4 that is generated when a requested file is not found for ZIP processing.
User-selectable
5.6 TEMP_SPACE_MULTIVOL Control multi-volume allocation of Temporary work files.
Y|N
5.5 CHECK_SYSIN_MEMBER Verifies a command input stored in Y|N
35
Release Command Description Values
a PDS or PDSE member.
5.5 DATA_TYPE(DETECTX) Provides automatic detection and translation of ASCII text during UNZIP processing (similar to DETECT for ZIP processing).
Default remains as “DETECT”.
5.5 EXCLUDE Enhanced file filtering capabilities. User-supplied
5.5 KEY_PROTECT_LEVEL Specifies a relative intensity of encryption key protection.
1 / 2
5.5 PKSUPPRC Allows the return code to be suppressed on certain conditions.
ZPAM092E - Nothing to do.
ZPAM093W - No Files match: Initializing/Copying Archive.
ZPEX013 - Truncation.
5.5 PRESERVE_CMD_SPACE Preserves or removes blanks proceeded by a “|”.
Y|N
5.5 SUPPRESS_DYNALLOC_MSGS Specifies that the dynamic allocation messages in job log be suppressed.
NODYNMSGS
Command Changes The default values for the following commands have been changed. When assembling an existing installation defaults module (ACZDFLT), these values should be reviewed for applicability and adjusted as required.
Upgrade Notes Installations suppressing the //SYSIN PDS member verification for performance
reasons with PROC_OPT1=N (available with PKZIP for MVS 5.0.10 maintenance) in ACZDFLT should change to CHECK_SYSIN_MEMBER=N in the assembly of ACZDFLT. PROC_OPT1 is longer used for this purpose in PKZIP for MVS Release 5.5 or SecureZIP for z/OS.
Installations controlling the //SYSPRINT DCB attributes with PROC_OPT2 (available with PKZIP for MVS 5.0.10 maintenance) in ACZDFLT should change to SYSPRINT_DCB in the assembly of ACZDFLT. PROC_OPT2 is no longer used for this purpose in PKZIP for MVS Release 5.5 or SecureZIP for z/OS.
Installations utilizing the filename case-insensitivity feature with PROC_OPT3=U (available with PKZIP for MVS 5.5.0 maintenance) in ACZDFLT should change to FILENAME_SELECT_CASE=U in the assembly of ACZDFLT. PROC_OPT3 is no longer used for this purpose in SecureZIP for z/OS.
Upgrade note: Installations previously using text translation tables other than EBC#8859 for TRANSLATE_TABLE_DATA or TRANSLATE_TABLE_FILEINFO should review the data translation characters used. The newer default tables in EBC#8859 use the IBM ICONV standard character sets for IBM-1047 EBCDIC and ISO-8859-1 ASCII.
36
In general, the newer default table is better for general-purpose text translation than the older ASCIIUS, ASCIIUSE, ASCIIUK, and ASCIIUKE tables. However, the older tables are still provided for compatibility in case installation-dependent processing requires translation of specialized character sets.
Release Command Old Values New Values
8.0 ENCRYPTION_METHOD STANDARD
AES128
AES192
AES256
STANDARD
AES128
AES192
AES256
BSAFE_AES128
BSAFE_AES192
BSAFE_AES256
BSAFE_DES
BSAFE_3DES
BSAFE_RC4
5.6 No changes since PKZIP for MVS 5.5
5.5 ARCHIVE_DIR_BLOCKS 10 56
5.5 ARCHIVE_SPACE_PRIMARY 100 10
5.5 ARCHIVE_SPACE_SECONDARY 100 10
5.5 ARCHIVE_SPACE_TYPE TRK CYL
5.5 ARCHIVE_UNIT SYSALLDA SYSDA
5.5 COMPRESSION_LEVEL NORMAL SUPERFAST
5.5 MULTI_THREAD_LIMIT 1 3
5.5 OUTFILE_SPACE_TYPE TRK CYL
5.5 OUTFILE_SPACE_PRIMARY 100 10
5.5 OUTFILE_SPACE_SECONDARY 100 10
5.5 OUTFILE_UNIT SYSALLDA SYSDA
5.5 PASSWORD Increased Maximum length to 200 characters.
5.5 PARMLIB_DSNAME_ZIP NULLFILE
5.5 PARMLIB_DSNAME_UNZIP NULLFILE
5.5 PROCESS_ALIAS N Y
5.5 SAVE_FILE_ATTRIBUTES BOTH CENTRAL
5.5 TEMP_UNIT NULL SYSDA
5.5 VSAM_SPACE_PRIMARY 100 10
5.5 VSAM_SPACE_SECONDARY 100 10
5.5 VSAM_SPACE_TYPE TRK CYL
37
Message Changes Messages have been added (along with some text changes) with this release of PKZIP/SecureZIP. A library compare of pkzip.MVS.HELP will show these changes relative to the release being migrated from.
Enhancements for Secure Data The following enhancements for strong security are included with release 9.0.
ICSF integration dynamically makes use of IBM cryptographic facilties for the most efficient use of system resources.
The following enhancements for strong security were included with release 8.2.
The password will no longer be echoed in the SYSPRINT stream. The value ‘PASSWORD(**********)” will be displayed instead.
Password information is not left in clear text within virtual storage during PKZIP/SecureZIP operations.
When entering passwords on the ISPF panels, the input field has been changed to non-display. A password verification field has been added on the password prompting screens to assist you in verifying that the correct password has been entered. However, the password may be displayed by selecting a panel option.
SecureZIP for z/OS supports encryption algorithms with keylengths of 128 and greater, including DES, 3DES, AES and RC4.
SecureZIP for z/OS supports filename encryption to prevent file names and file metadata from being visible.
PKZIP Enterprise Edition supports the decryption of strongly encrypted files from a SecureZIP source.
SecureZIP for z/OS Enterprise Edition supports certificate-based encryption.
SecureZIP for z/OS Enterprise Edition supports signing and authentication using digital certificates.
Restrictions for PKZIP and SecureZIP for z/OS
The following restrictions apply:
The integrity of the ZIP archive is not impaired in any way and archived files can be extracted successfully. However, the temporary dataset name of the ZIP archive should be changed to the name required by you after PKZIP/SECZIP has completed.
When two (or more) files from a ZIP archive are extracted with the same MVS dataset name, the last file will overwrite any previous file(s).
When a dataset is spread over more than 31 volumes, PKZIPz may not restore the dataset to the identical volumes.
38
Extracting to a GDG dataset via OUTFILE_DD will result in the use of the user-specified DCB values. The user must ensure that these values are appropriate to the record lengths being written.
The number of files or PDS members that can process in one operation may be restricted by the number of concurrent DD’s that can be used in the address space, such as, the size of the TIOT. For further information on this limit, see the documentation for DD statements in the IBM JCL User’s Guide.
Some IDCAMS DEFINE Cluster options can be specified at the Cluster and Data (and Index if appropriate) levels. However, a few of these options, when specified using ARCH* or OUT* commands during PKZIP/SECZIP or PKUNZIP/SECUNZIP operations, will set only the Data (and Index) components. This is because some ARCHIVE_* and OUTFILE_* commands which apply to Cluster, Data, and Index components, currently set both the data and index attributes, and ignore the Cluster level component. These may in future, set the Cluster level option only. Commands that may change in this way are shown in the following table. For these commands, it is recommended that the ARCHDATA* and ARCHINDX, or OUTDATA* and OUTINDX* options be used.
SECUNZIP Command
Comments
ARCHEEXT Is effectively the same as setting both ARCHDATAEEXT and ARCHINDXEEXT.
ARCHOWNER Is effectively the same as setting both ARCHDATAOWNER and ARCHINDXOWNER.
OUTEEXT Is effectively the same as setting both OUTDATAEEXT and OUTINDXEEXT.
OUTOWNER Is effectively the same as setting both OUTDATAOWNER and OUTINDXOWNER.
PDS members containing positioning information (for example load members with overlay sections) are not supported. In certain circumstances these might be processed with unpredictable results.
PDSE program objects are not currently supported in native format. IEBCOPY should first be used to offload the PDSE Library to a sequential file and the resulting sequential file can be archived. Subsequently, after extracting the unloaded version of the PDSE, it can be reloaded with IEBCOPY.
GZIP (GNU zip) file processing has a number of restrictions as documented in Chapter 12.
Dataset alias entries can be used to select datasets, however, the true name will be used to process filename associations in the archive. The dataset alias name is not retained.
Values for dynamic allocation requests by PKZIPz may be added, altered, or removed by installation-dependent storage management services, for example, DF/SMS. Allocation results may be different from those specified by PKZIPz commands or default values.
39
PKZIPz makes use of access method services user I/O routines for SYSIN and SYSPRINT file requests. OEM products and/or installation-written routines that modify standard IBM processing for these exits should not be active during PKZIP/SECZIP processing.
Data types found natively in the OS/390 and zOS environments, such as binary load modules, may not be usable on other platforms. That is, PKZIPz does not convert executable programs from one system platform to another.
Although it is possible for archives to be appended to other archives in a dataset during a ZIP process—for example, DISP(=MOD,CATLG, in MVS, or using the UNIX append”>>” operator for files)—this is not recommended. The result is that “dead” archives are carried along in the file, and various ZIP products will read the file differently, with some looking for the ZIP archive directory structure from the beginning, others from the end of the file.
PKZIPz attempts to read the first archive found from the beginning of the file, for performance reasons and to perfom an archive integrity check. If an inconsistency in the initial header structures exist, a secondary search from the back of the archive will be attempted. PKZIPz will accept up to 64k of non-archive data at the end of the archive file when searching for the end of the directory (from the back). This limit does not apply when the local directory structure is intact.
For more information regarding data formats, see Chapter 8.
PKZIPz is designed to work with archives and compression methods starting with the PKZIP 2.x standard. Although the implode algorithm was used in PKZIP 1.x, SecureZIP for zSeries 8.2 retains the ability to extract the older compression method’s files.
Internal to the Zip archive, file dates are saved as a count of the number of years from 1980. Because only six bits are used to store this date, a limit of 64 years (2**^) can be symbolized. This representation will successfully allow dates to be shown through the year 2043.
IBM has restricted licensing for some components of zOS.e, such as Language Environment Compatibility Preinitialization (CEEPIPI) for some languages. Therefore some languages cannot be used for the PKZIP/SECZIP User API facility when running under zOS.e. (SecureZIP for z/OS uses CEEPIPI to prepare the language environment for high-level language user API programs.)
Region Size and Storage
Older versions of PKZIP (v2.x) used work files to translate and then compress data before adding it to an archive file. Using these work files, very little REGION space was needed to run a job, since this space was used to handle the processing once the REGION had been consumed. Note that this approach can create a substantial amount of I/O.
PKZIPz recommends the REGION value of 32M or higher. A value greater than 16,384K or 16M and less than or equal to 32,768K or 32M gives the job all the storage available below 16 megabytes. The resulting size of the region below 16 megabytes is installation-dependent. The extended region size is the default value of 32 megabytes. The purpose behind this requirement is to increase speed and reduce I/O. However, if you run out of virtual storage
40
then temporary files must be used to hold work space information. MEMORY_MODEL(MEDIUM or SMALL), will give PKZIP/SECZIP the outlet that it needs to handle the condition.
PKZIP/SECZIP processing, attempts to keep file management control information and compressed data in 31-bit virtual storage to maximize performance. In the event that 31-bit storage is constrained (by combinations of installation restrictions, high file volumes, and high data volumes), the following commands may be used to reduce 31-bit storage requirements for a given run.
DATA_STORAGE
MULTI_THREAD_LIMIT
MEMORY_MODEL(SMALL|MEDIUM|LARGE) controls where file management control blocks are held, such as, control blocks describing an archive file with its attributes.
When MEMORY_MODEL(LARGE) is specified or defaulted, all PKZIP/SECZIP control blocks are held in 31-bit virtual storage.
When either SMALL or MEDIUM is specified, the file descriptor information is spilled to a set of work files to be sorted, merged, and selected. Note that file descriptors are built for both files existing in the input archive and new files to be selected, so the aggregate count must be managed. Approximate sizes for each file descriptor are as follows:
VSAM - 2.5K.
Sequential - 800 bytes.
PDS/PDSE - 800 bytes for base dataset + 224 bytes per member.
DATA_STORAGE(MAX|xM) controls the amount of 31-bit virtual storage used to hold transient compressed data. When the amount of storage specified is exceeded, the data is processed through work files (controlled by the TEMP_... suite of commands).
MULTI_THREAD_LIMIT(number) specifies the number of concurrent subtask sets to run for ZIP or UNZIP processing. When a count greater than 1 is used, additional copies of modules, work areas, and buffers are allocated to handle the processing.
Some SecureZIP operations require additional virtual storage to operate successfully. In particular, activation of certificate-based operations (for example, recipient-based encryption and digital signature operations) may necessitate increasing the 31-bit region size. It is recommended that the user evaluate the virtual storage used by a SecureZIP step in relation to the number of digital certificates used for a particular process and establish an appropriate REGION size.
SMS Dataclass Considerations
SecureZIP parameters overlap with several SMS data class parameters. In general, SMS data class specifications will provide default values in place of SecureZIP default settings. Explicit SecureZIP commands (SYSIN, PARMLIB, included command streams and EXEC PARM values) will be presented to dynamic allocation as overrides for any default setting.
Due to the way DFSMS handles override requests, sub-groups of parameters are defined in SecureZIP to assist with control of where default values should come from. These subgroups are:
41
Allocation SPACE
Directory Blocks
Volume Count
DCB Attributes
DFSMS data classes may or may not contain values for all of the attribute sets above. SecureZIP provides a means of identifying which sets of attributes should be expected to be handled by SMS data classes so that SecureZIP does not specify its own default values. (DFSMS receives control after SecureZIP has built its list and does not provide a means by which SecureZIP can systematically pre-determine which values will be provided by SMS).
DFSMS groups allocation type (cylinders, tracks, etc.), primary space, and secondary space into a category. If even one of these values is provided in an allocation request, then SMS will not provide its default values for the remaining entries.
For example, if ARCHIVE_SPACE_PRIMARY is provided as a command, then SecureZIP needs to supply the TYPE and SECONDARY default values even if a DATACLASS is specified.
DFSMS treats the Directory Block allocation value separately from other space parameters. In the previous example, SecureZIP will not provide its default ARCHIVE_DIRBLKS value even though it provides the other allocation attributes. This is consistent with SMS data class operations.
SecureZIP makes use of temporary files during various phases of processing that have very specific DCB attribute requirements. For this reason, SecureZIP will specify the necessary overrides regardless of TEMPFILE_DATACLASS usage.
Note for users of PKZIP for MVS and PKZIP for zSeries 5.6 Previous levels of maintenance for release 5.6 specified a volume count even if it was 1. The maintenance level associated with fix TT1777 eliminated VOLCNT=1 from the allocation request. In addition, the maximum number specified for any of the MULTIVOL=Y commands is now 59 to be consistent with system limitations for DASD devices. If a unit type other than DASD is assigned (either explicitly or indirectly through SMS), and a volume count greater than 59 is desired, then MULTIVOL=N should be specified in SecureZIP, and an SMS data class should be designated which can assign the desired volume count.
Reserved DDNAMEs
The following DDNAMES are reserved for use by SecureZIP for z/OS:
ARCHTEMP - used for STAGE_TAPE_TO_DISK(y).
PKSPRINT - alternate SYSPRINT DD name when directed to a file.
ZPDIRIN - used when processing requires input archive file descriptors to be spilled to work file.
ZPDIRSRT - used when processing requires input archive file descriptors to be sorted in a work file.
ZPFILIN - used when input file descriptors requires sorting.
42
ZPFILSRT - used when input file descriptors require sorting.
ZIPCDS - license control dataset.
FNETMPCD - used for various FILENAME_ENCRYPTION processes.
The following DDNAMES are reserved, but may be modified with a customized ACZDFLT module:
ARCHIN - ARCHIVE_INFILE
ARCHOUT - ARCHIVE_OUTFILE
PARMLIB - DDNAME_PARMLIB
SYSIN - DDNAME_SYSIN
SYSPRINT - DDNAME_SYSPRINT
ZPSRTIN - DDNAME_ZPSORTIN
ZPSRTOUT - DDNAME_ZPSORTOUT
SYSPRINT By default (unless overriden in the ACZDFLT module with DDNAME_SYSPRINT, //SYSPRINT is used for PKZIP/SECZIP logging. This does not conflict with utilities used internally unless the SYSPRINT is directed to a physical file . Because utilities such as SORT may use a different set of DCB characteristics than PKZIP/SECZIP, a change to PKSPRINT for sysout will occur. The command form –DDNAME_SYSPRINT= may also be used in the EXEC parms with JCL or by a calling program to redirect messages to a different location.
PKSPRINT //PKSPRINT is used when the SORT utility is internally invoked and the //SYSPRINT DD statement is determined to be allocated as a non-JES SYSOUT file. If not already allocated to the jobstep, PKZIP/SECZIP will dynamically allocate this DD to the SYSOUT= value specified in SYSPRINT_SYSOUT_CLASS from the installation defaults module.
PKNODUMP If allocated to the job step before invoking PKZIP/SECZIP, a //SYSABEND DD will not be dynamically allocated.
Use of System Utilities
SORT SecureZIP for z/OS uses the system SORT utility to manage archive directory entries, during both match/merge procedures and View processing.
43
Access Method Services SecureZIP for z/OS invokes this utility to locate cataloged files, define VSAM clusters, and handle Delete/Rename processing for an updated archive.
IEBGENER IEBGENER is called to open the PANVALET input stream (according to the DDNAME_SYSIN specification in the active ACZDFLT module) and copy the data. The temporary file will be dynamically allocated with the TEMP_SPACE_TYPE settings.
GRS/ENQ Data set serialization is normally performed through the use of the allocation DISP value. This makes use of the SYSDSN major name for GRS/ENQ processing.
When archive creation or update processing is performed with dynamic allocation, a temporary ZIP archive data set is created with DISP=NEW,CATLG. The input archive (if one exists) is allocated as DISP=OLD to ensure that only one update process is performed against the logical archive at a time. Once the temporary target archive has been successfully updated, the original input archive is deleted, and the new temporary archive is renamed to the original name.
When an output archive or extract target (outfile) is intended to be a member of a partitioned data set, an allocation is performed for the data set with a disposition in accordance with the setting for OUTFILE_PDS_ENQ. In addition, an exclusive ENQ with a major name of SPFEDIT is performed against the member.
SecureZIP for z/OS update processing for administration of the local certificate store uses DISP=OLD serialization against the VSAM Cluster specified in the profile for CSPUB_DBX=. Run-time processing for PKZIP/SECZIP performs a SYSDSN ENQ for this data set as DISP=SHR. This allows multiple run-time users for certificate store searches, or one administrative update process. Jobs requiring read access for locating certificates wait until an update process completes and then continue processing.
License control data set (ZIPCDS DD) access is normally performed with DISP=SHR allocation. However, when a newly accessed feature requires that an update be done, an additional ENQ is performed using QNAME(PKZIPCDS) for the update process to serialize on.
The PKZIPz programs are not re-entrant. To protect run-time integrity against inadvertent simultaneous calls into the mainline programs, a STEP level ENQ is performed with QNAME(PKZIP) RNAME(RUNNING).
44
4 Licensing
Operating Requirements
The use of the PKZIP and SecureZIP product line for z/OS requires the activation of a PKWARE-provided license key. A set of licensing messages will be shown at the front of the SYSPRINT output for each invocation of PKZIP or SecureZIP.
Change of Release Licensing
Note: Each release of PKZIPz requires that a new PKWARE license key be activated. If the license data set from a previous release is used, the new release will fail with the message ZPLI901E Product License is Invalid.
Grace Period PKWARE recognizes that there may be periods where the licensing environment established by the customer is no longer valid. Circumstances such as disaster recovery processing or the installation or upgrade of new processors will affect the environment.
When a grace period has been activated, error messages will be displayed on the console (and in the output) for each execution of PKZIPz. At the end of the period, if the license is not updated, the product will no longer function for the new CPUs except to VIEW an archive. The five-day grace period is designed so that the program will not cease to function on a weekend or the Monday following the five-day grace period. You must contact PKWARE at [email protected] during the grace period to obtain licensing to allow extended use.
Initializing the License
Refer to the PKZIP/SecureZIP for z/OS System Administrator’s Guide for license administration details.
45
5 Getting Started with PKZIP and SecureZIP
PKZIP/SecureZIP for z/OS are broad, flexible products on the OS/390 and z/OS platforms, allowing for compression/decompression and encryption of files. They are fully compliant with other ZIP-compatible compression products running on other operating systems. However, if you are licensed for SecureZIP for z/OS, its advanced security features are only compatible with designated PKWARE products also enabled for these features.
Because the ZIP standard for text data storage is ASCII, PKZIPz facilitates conversion between the ASCII and EBCDIC character sets. Therefore, compressed text files can be transferred between IBM mainframe environments and systems using either character set. Some of these platforms include DOS, Windows, UNIX/Linux, and iSeries.
In addition to ZIP archive format support, PKZIPz can also produce and manipulate (GNU) GZIP-format archives. Additional information on this subject can be found in Chapter 12.
Introduction to PKZIP and SecureZIP for z/OS
PKZIP for z/OS consists of two separate executable programs:
PKZIP - Compresses datasets into an archive.
PKUNZIP - Decompresses and extracts datasets from an archive
SecureZIP for z/OS consists of two separate executable programs:
SECZIP - Compresses datasets into an archive.
SECUNZIP - Decompresses and extracts datasets from an archive
Note: For installations upgrading from PKZIP for z/OS to SecureZIP for z/OS, the PKZIP and PKUNZIP program names are maintained as ALIAS entries for compatibility. There is no operational difference when using the PKZIP/PKUNZIP program names versus the SECZIP/SECUNZIP counterparts.
To use these programs, you must specify:
Commands, which tell PKZIP/SECZIP or PKUNZIP/SECUNZIP what processing they are to perform and how they are to do it. Commands are identified by a preceding hyphen
46
(“–”). For example, –ARCHIVE_DSN is the command that designates the dataset name for the ZIP archive containing compressed data.
File selections, which identify the files to be compressed into an archive (ZIP) or decompressed from an archive (UNZIP). File selections are distinguished from commands because they are not preceded by a hyphen.
Commands and file selections can be specified in a number of ways. The most common way, which is the way that will be used in the examples presented in this chapter, is to run PKZIP/SECZIP and PKUNZIP/SECUNZIP as batch jobs using JCL and specify the commands and file selections through SYSIN, as shown in the next section.
Invoking PKZIP/SECZIP or PKUNZIP/SECUNZIP Using JCL
In these examples, you will be running PKZIPz in batch by submitting JCL. The product can also be executed using the ISPF panels interface, called from a user written program, or from a TSO environment with REXX or CLISTS.
The example below demonstrates the basic JCL statements required to run PKZIP.
//<job card>1 //ZIP EXEC PGM=PKZIP2,REGION=8M3 //STEPLIB4 DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT5 DD SYSOUT=* //SYSIN6 DD * -ARCHIVE_DSN(MY.ARCHIVE.ZIP) 7 <commands>7 /* //
Notes on the preceding example
1. <job card> should be replaced with the job details required for running this job, in accordance with your installation standards.
2. To add, update, freshen, delete, or view compressed files within a ZIP archive, use the ‘PKZIP’ program. To extract, test, or view compressed files in a ZIP archive use the ‘PKUNZIP’ program.
3. PKZIPz should normally run within a region size of 32Mb; however, this value is dependent on the number and type of files being processed. If you encounter storage problems, then this value should be increased if possible.
4. STEPLIB specifies the library that contains PKZIPz. The load library may be placed in the JOBLIB DD or in one of the libraries shared by all zOS processing, for example, LNKLST, in which case there is no need to use the STEPLIB DD.
5. SYSPRINT contains all the message output. A SYSABEND DD card will be dynamically allocated by default if one is not supplied.
6. SYSIN is the usual mechanism for supplying commands. Alternatively you can use the PARM parameter on the EXEC statement, the //PARMLIB DD, or a combination of all three.
7. Commands, such as this one, specify the processing to be carried out.
47
Return Codes A completion code dependent on the results of the processing that was carried out will be issued. The completion code can take the following values:
0 Processing has completed without errors being detected.
4 A warning message has been output but processing has continued.
6 An authentication error was encountered while processing a signed archive central directory or File.
8 or higher An error has occurred during processing; refer to the error messages for more details.
12 A syntax error or configuration setup error was encountered. The command and/or combination of commands should be reviewed. The error can include inappropriate processing when attempting to locate digital certificates for encryption or authentication functions.
The final completion code issued is the maximum value of the conditions found during the sum. A return code greater than zero indicates that there are one or more warning or error messages in the job output.
Compressing a Dataset
The following example shows how to compress a data set using PKZIPz.
//ZIP EXEC PGM=PKZIP,REGION=8M //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.V56.LOAD //SYSPRINT DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSNAME(MY.ARCHIVE.FILE.ZIP) -ARCHIVE_UNIT(SYSDA) MY.INPUT.DATA.SEQ /*
This step will give the following output:
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 -ARCHIVE_DSN(MY.ARCHIVE.FILE.ZIP) -ARCHIVE_UNIT(SYSDA) MY.INPUT.DATA.SEQ ZPAM030I OUTPUT Archive opened: MY.ARCHIVE.FILE.ZIP ZPAM253I ADDED File MY.INPUT.DATA.SEQ ZPAM254I as MY/INPUT/DATA/SEQ ZPAM255I (DEFLATED 93%/93%) ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
In this case, the sequential data set MY.INPUT.DATA.SEQ is to be compressed into the new ZIP archive MY.ARCHIVE.FILE.ZIP, which is created on a SYSDA volume.
48
Notes for Dataset Compression A ZIP archive can be considered as a large envelope or box into which the compressed
files are placed. Note, however, that an empty dataset is not the same as an empty archive. ZIP archives created by PKZIPz cannot be pre-allocated; only PKZIPz should be used to create new archives.
You tell PKZIP how to create the ZIP archive. By default ZIP archives are created as sequential datasets and allocated using half track blocking. However, you have full control over the type of archive created and how it is created using the various ARCHIVE_* commands.
PKZIP compresses datasets using a file selection. Any command that does not begin with a “–” is considered to be a file selection. In the previous example, we told PKZIP to compress the sequential dataset MY.INPUT.DATA.SEQ.
You can specify a file for compression via an INFILE_DD statement if you prefer, but a file selection has the advantage of wildcards. For example, to compress a specific group of files, you could type MY.INPUT.DATA.*. This file selection would inform PKZIP to compress every dataset that begins with the previous qualifying nodes. PKZIP can compress up to 65,535 datasets or up to 4Gb of data.
To ensure cross platform compatibility, all MVS dataset names are converted to the standard PKZIP UNIX format, such as, MY/INPUT/DATA/SEQ. When you unzip the file, the conversion is reversed to recreate the original MVS name. See ZIPPED_DSN_SEPARATOR for more information about the character used to separate levels.
The compressed version of the sequential data set in a ZIP archive is sometimes called a zipped file.
Viewing the Contents of an Archive
The following example shows how to use SecureZIP for z/OS to view the contents of the ZIP archive created in the previous example.
//STPZIP EXEC PGM=PKZIP //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(MY.ARCHIVE.FILE.ZIP) -ACTION(VIEW) /*
This step yields output similar to the following:
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 -ARCHIVE_DSN(MY.ARCHIVE.FILE.ZIP) -ACTION(VIEW) ZPAM030I INPUT Archive opened: MY.ARCHIVE.FILE.ZIP ZPAM014I There are 1 file(s) in the input Archive.
49
ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE ZPAM013I ********************************************************************** ZPAM015I Length Method Size Ratio Date Time CRC-32 Name ZPAM016I ------------- ------------ ------------- ----- ---------- ZPAM017I 1,067 Dflt-Norm 81 92% 01/16/2006 11:54 C7A3091B MY/INPUT/DATA/SEQ ZPAM016I ------------- ------------ ZPAM019I 1,067 81 92% ZPAM013I *********************************************************************** ZPAM140I FILES: VIEWED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Notes for Viewing the Contents of an Archive The ACTION(VIEW) command is available through the ZIP program (PKZIP/SECZIP).
The ACTION(VIEW) command has various options that can be used to tailor the output. For example, if the archive contains multiple files, the output can be sorted by the file’s attributes, including name, size, and compression ratio.
This example demonstrates a standard view of the archive. It displays information about the files in the archive including the original length of the file, the compression method, and the compressed file size.
ACTION(VIEWDETAIL One especially useful option is the ACTION(VIEWDETAIL) ) control card. It displays the full technical details, including any file attributes stored, for each file in the archive.
//STPZIP EXEC PGM=PKZIP //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(MY.ARCHIVE.FILE.ZIP) -ACTION(VIEWDETAIL) /*
This step produces output like the following:
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 -ARCHIVE_DSN(MY.ARCHIVE.FILE.ZIP) -ACTION(VIEWDETAIL) ZPAM030I INPUT Archive opened: MY.ARCHIVE.FILE.ZIP ZPAM014I There are 1 file(s) in the input Archive. ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE ZPAM013I ****************************************** ZPAM001I Filename: MY/INPUT/DATA/SEQ ZPAM002I File type: TEXT ZPAM003I Date/Time: 16-JAN-2006 11:54:06 ZPAM004I Compression Method: Deflate- Normal ZPAM005I Compressed Size: 81 ZPAM006I Uncompressed Size: 1,067 ZPAM007I 32-bit CRC: C7A3091B ZPAM008I Created by: PK z/OS 9.0 ZPAM009I Needed to extract: ZipSpec 2.0
50
ZPAM301I File Type: NONVSAM SEQUENTIAL ZPAM303I File Record Format: FB ZPAM304I File Allocation Type: TRK ZPAM305I File Primary Space Allocated: 1 ZPAM306I File Secondary Space Allocated: 1 ZPAM307I File Record Size: 80 ZPAM308I File Block Size: 3120 ZPAM309I File Volume(s) Used: SUP001 ZPAM310I File Creation Date: 2006/01/14 ZPAM311I File Referenced Date: 2006/01/16 ZPAM319I SMS Management Class: SUPPORT ZPAM000I SMS Storage Class: SUPPORT ZPAM013I ********************************************************* ZPAM140I FILES: VIEWED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Note: The order in which attributes are displayed may vary.
Decompressing a Dataset
The following example shows how to extract, or unzip, a data set using SecureZIP for z/OS.
//UNZIP EXEC PGM=PKUNZIP,REGION=8M //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(MY.ARCHIVE.FILE.ZIP) -OUTFILE_UNIT(SYSDA) /*
This step produces output like the following:
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 -ARCHIVE_DSN(MY.ARCHIVE.FILE.ZIP) -OUTFILE_UNIT(SYSDA) ZPAM030I INPUT Archive opened: MY.ARCHIVE.FILE.ZIP ZPEX002I MY/INPUT/DATA/SEQ ZPEX003I Extracted to MY.INPUT.DATA.SEQ ZPAM140I FILES: EXTRACTED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Notes for Decompressing a Dataset To extract files from an archive, you must call the PKZIP/SECUNZIP program.
The extracted dataset is created dynamically according to the stored file attributes, if any, or the OUTFILE DD attributes supplied in the job allocation. In this case, the dataset is recreated on a SYSDA volume. Information required to create the dataset
51
that is not provided by the stored file attributes or by the OUTFILE allocation may be defaulted by PKUNZIP/SECUNZIP.
By default, PKUNZIP/SECUNZIP tries to extract every file that is compressed and stored inside the ZIP file or archive. To extract just one file, or selected files, you must explicitly select the files you wish to extract or decompress. Wildcards can be used in the file selection to have PKUNZIP/SECUNZIP extract a suite of like datasets.
If the extracted dataset already exists, then (by default) PKUNZIP/SECUNZIP does not overwrite it.
To overwrite a dataset or PDS member, use the OUTFILE_OVERWRITE command. To add new members to existing PDS's, use the INSERT_MEMBER command. Alternatively you can use the UNZIPPED_DSN command to give the extracted file a new name.
Updating or Refreshing a File
You cannot ACTION(ADD) a file that already exists in a ZIP archive. However, you can replace it by using the ACTION(UPDATE) or ACTION(FRESHEN) commands.
The ACTION(UPDATE) and ACTION(FRESHEN) commands differ in their processing of files that do not already exist in the archive: If a file selected for compression does not already exist in the archive, ACTION(UPDATE) adds it, but ACTION(FRESHEN) ignores it.
Invoking the PKZIP and SecureZIP for z/OS Utility
There are several ways to use PKZIPz in the OS/390 and z/OS operating environments. These include:
Batch JCL job-steps.
Started task JCL.
Executed from TSO CLIST/REXX.
TSO command line interface.
ISPF panel.
The following sections provide a brief overview of these interfaces. Subsequent sections in this chapter describe basic functions using the JCL interface.
Invoking PKZIP/SecureZIP from JCL (Batch or Started Task)
PKZIPz programs can be executed from a batch job or STC. See pkware.mvs.INSTLIB(IVPBASIC) for a sample JOB, or use the ISPF interface to generate JCL for a batch job.
Invoking PKZIP/SecureZIP as Called Programs Under TSO
PKZIPz batch interface programs can be executed within a TSO CLIST or REXX EXEC provided that the proper FILE allocations (TSO equivalent of DD statements) are made.
52
The following samples show how allocations can be done to invoke PKZIPz.
CLIST Call - Read commands from a member and put messages to a pre-allocated FB132 file.
PROC 0 ALLOC F(SYSIN) DA('pkware.mvs.INSTLIB(SAMPVIEW)') SHR ALLOC F(SYSPRINT) DA('USERID.QZ.SYSOUT') SHR CALL 'pkware.mvs.LOAD(PKUNZIP)' FREE F(SYSIN,SYSPRINT)
REXX Call - Pass commands as a parm and allocate a new SYSPRINT file to browse.
/* Rexx Sample call of SECUNZIP for -VIEW with no SYSIN */ /* First allocate a SYSPRINT output file for later browsing */ Address TSO "attrib dcbout recfm(f b) lrecl(132) blksize(27984)" "ALLOC F(SYSPRINT) da(my.sysprint) new catalog cylinders " , "using(dcbout) space(1,1)" /* Define the command list to pass (without SYSIN) */ callparms = "-NOSYSIN -ARCHIVE(USERID.MY.ZIP) -VIEWBRIEF" /* Invoke SECUNZIP */ Address LINKMVS "SECUNZIP callparms" /* Free the work files and browse the output */ Address TSO "free f(DCBOUT,SYSPRINT)" Address ISPEXEC "browse dataset(my.sysprint)"
Invoking ZIP or UNZIP TSO Command Line Interface
A subset of PKZIPz features can be invoked from the ZIP and UNZIP REXX EXECs. These commands are intended to approximate the PKZIP and PKUNZIP DOS-based commands with similar command syntax. In addition to the standard commands being passed as input options, several shorthand Actions and Options are provided with this interface (see the tables below).
Syntax ZIP <-action> [-options] <Archive_name> <File_names>
UNZIP <-action> [-options] <Archive_name> <File_names>
53
Valid ZIP Actions
'–a' '–ACTION(ADD)'
'–d' '–ACTION(DELETE)'
'–f' '–ACTION(FRESHEN)'
'–u' '–ACTION(UPDATE)'
'–v' '–ACTION(VIEW)'
'–vbd' '–ACTION(VIEWDATE)'
'–vn' '–ACTION(VIEWNAME)'
'–vo' '–ACTION(VIEWOFFSET)'
'–vp' '–ACTION(VIEWPERCENT)'
'–vs' '–ACTION(VIEWSIZE)'
'–vr' '–ACTION(VIEWREVERSE)'
'–vrd' '–ACTION(VIEWDATEREVERSE)'
'–vrn' '–ACTION(VIEWNAMEREVERSE)'
'–vro' '–ACTION(VIEWOFFSETREVERSE)'
'–vrp' '–ACTION(VIEWPERCENTREVERSE)'
'–vrs' '–ACTION(VIEWSIZEREVERSE)'
'–vb' '–ACTION(VIEWBRIEF)'
'–vbd' '–ACTION(VIEWBRIEFDATE)'
'–vbn' '–ACTION(VIEWBRIEFNAME)'
'–vbo' '–ACTION(VIEWBRIEFOFFSET)'
'–vbp' '–ACTION(VIEWBRIEFPERCENT)'
'–vbs' '–ACTION(VIEWBRIEFSIZE)'
'–vbr' '–ACTION(VIEWBRIEFREVERSE)'
'–vbrd' '–ACTION(VIEWBRIEFDATEREVERSE)'
'–vbrn' '–ACTION(VIEWBRIEFNAMEREVERSE)'
'–vbro' '–ACTION(VIEWBRIEFOFFSETREVERSE)'
'–vbrp' '–ACTION(VIEWBRIEFPERCENTREVERSE)'
'–vbrs' '–ACTION(VIEWBRIEFSIZEREVERSE)'
'–vt' '–ACTION(VIEWDETAIL)'
'–vtd' '–ACTION(VIEWDETAILDATE)'
54
Valid ZIP Options
'–vtn' '–ACTION(VIEWDETAILNAME)'
'–vto' '–ACTION(VIEWDETAILOFFSET)'
'–vtp' '–ACTION(VIEWDETAILPERCENT)'
'–vts' '–ACTION(VIEWDETAILSIZE)'
'–vtr' '–ACTION(VIEWDETAILREVERSE)'
'–vtrd' '–ACTION(VIEWDETAILDATEREVERSE)'
'–vtrn' '–ACTION(VIEWDETAILNAMEREVERSE)'
'–vtro' '–ACTION(VIEWDETAILOFFSETREVERSE)'
'–vtrp' '–ACTION(VIEWDETAILPERCENTREVERSE)'
'–vtrs' '–ACTION(VIEWDETAILSIZEREVERSE)'
'–ex' '–COMPRESSION_LEVEL(MAXIMUM)'
'–en' '–COMPRESSION_LEVEL(NORMAL)'
'–ef' '–COMPRESSION_LEVEL(FAST)'
'–es' '–COMPRESSION_LEVEL(SUPERFAST)'
'–e0' '–COMPRESSION_LEVEL(STORE)'
‘–s…’ secure with encryption where “…”=password
‘–noprompt’ When being run from an ISPF environment, the default is for the interpreted commands to be displayed in an EDIT session allowing you an opportunity to alter the commands. This option will bypass this feature, as well as, the ISPF browse of SYSPRINT when the function is complete.
Valid UNZIP Actions
'–e' '–ACTION(EXTRACT)'
'–o' '–OUTFILE_OVERWRITE(Y)'
'–v' '–ACTION(VIEW)'
'–t' '–ACTION(TEST)'
'–vbd' '–ACTION(VIEWDATE)'
'–vn' '–ACTION(VIEWNAME)'
'–vo' '–ACTION(VIEWOFFSET)'
'–vp' '–ACTION(VIEWPERCENT)'
'–vs' '–ACTION(VIEWSIZE)'
'–vr' '–ACTION(VIEWREVERSE)'
'–vrd' '–ACTION(VIEWDATEREVERSE)'
'–vrn' '–ACTION(VIEWNAMEREVERSE)'
55
'–vro' '–ACTION(VIEWOFFSETREVERSE)'
'–vrp' '–ACTION(VIEWPERCENTREVERSE)'
'–vrs' '–ACTION(VIEWSIZEREVERSE)'
'–vb' '–ACTION(VIEWBRIEF)'
'–vbd' '–ACTION(VIEWBRIEFDATE)'
'–vbn' '–ACTION(VIEWBRIEFNAME)'
'–vbo' '–ACTION(VIEWBRIEFOFFSET)'
'–vbp' '–ACTION(VIEWBRIEFPERCENT)'
'–vbs' '–ACTION(VIEWBRIEFSIZE)'
'–vbr' '–ACTION(VIEWBRIEFREVERSE)'
'–vbrd' '–ACTION(VIEWBRIEFDATEREVERSE)'
'–vbrn' '–ACTION(VIEWBRIEFNAMEREVERSE)'
'–vbro' '–ACTION(VIEWBRIEFOFFSETREVERSE)'
'–vbrp' '–ACTION(VIEWBRIEFPERCENTREVERSE)'
'–vbrs' '–ACTION(VIEWBRIEFSIZEREVERSE)'
'–vt' '–ACTION(VIEWDETAIL)'
'–vtd' '–ACTION(VIEWDETAILDATE)'
'–vtn' '–ACTION(VIEWDETAILNAME)'
'–vto' '–ACTION(VIEWDETAILOFFSET)'
'–vtp' '–ACTION(VIEWDETAILPERCENT)'
'–vts' '–ACTION(VIEWDETAILSIZE)'
'–vtr' '–ACTION(VIEWDETAILREVERSE)'
'–vtrd' '–ACTION(VIEWDETAILDATEREVERSE)'
'–vtrn' '–ACTION(VIEWDETAILNAMEREVERSE)'
'–vtro' '–ACTION(VIEWDETAILOFFSETREVERSE)'
'–vtrp' '–ACTION(VIEWDETAILPERCENTREVERSE)'
'–vtrs' '–ACTION(VIEWDETAILSIZEREVERSE)'
To compress and store all of a user’s files into an archive, type the following:
ZIP –a 'MY.CLI.TEST.ZIP' '&SYSUID.** '
56
Invoking the PKZIP and SecureZIP for z/OS ISPF Panel Interface The ISPF panel interface provides a simple way for a TSO user to either build batch JCL or invoke foreground PKZIPz services. The panel interface also provides a dynamic table interface to display ZIPPED files within a ZIP archive allowing line-command selection for browsing, viewing, and extracting.
SecureZIP Version 9.0 Option ===> C Config Modify Run-time Configuration Settings ZD Zip Defaults Modify Default ZIP Command Settings UD Unzip Defaults Modify Default UNZIP Command Settings U Unzip Decompress, Decrypt, Authenticate File(s) in an Archive V View Display the Contents of a Zip Archive Z Zip Compress, Encrypt, Sign File(s) into a Zip Archive S Sysprint Browse Log of Last Foreground Execution M Messages Message ID lookup A Administration Administration Services and Reference Information For HELP Press PF1 Release Date: 06/26/2006 07.22 LVL(0)
The ISPF interface is covered in detail in Chapter 13. See the PKZIP/SecureZIP for z/OS System Administrator’s Guide for instructions on installaton and implementation.
Configuration Manager
In releases of PKZIP for MVS version 2, users were allowed to create a configuration file that allowed PKZIP to accept different parameters during a run of PKZIP or PKUNZIP. PKZIPz has extended the means of allowing the user to control the defaults that PKZIP/SECZIP and PKUNZIP/SECUNZIP use during a job.
First, edit PKWARE.MVS.INSTLIB(ACZDFLT) to set defaults for PKZIP. These defaults are then assembled into PKWARE.MVS.LOAD by using the ASMDFLT member of INSTLIB. The ACZDFLT's module gives you extended flexibility to make PKZIP work the way you want it to.
ACZDFLT is a data-only CSECT that uses macro MCZDFLTS to generate the table data. An installation can customize the values for this module by adding appropriate variable data to the invocation of MCZDFLTS in the ACZDFLT module source.
Multiple versions of ACZDFLT may be assembled and linked into an execution load library for use with the DM execution parameter. Doing this allows multiple configurations to be pre-defined and used. In addition to the //PARMLIB DD for the configuration file, //CONFIG DD is also supported for compatibility with PKZIP for MVS version 2.
Making Changes to the Defaults Within the ACZDFLT’s member, one variable (at least) must coincide with your installation’s PKZIP high-level qualifier. This variable is the LICENSE_HLQ parameter. PKZIP accesses your
57
PKWARE.MVS.LICENSE data set during every execution of ZIP or UNZIP. Providing your installation’s high level qualifier for the LICENSE_HLQ parameter tells PKZIP where to find it.
*********************************************************** MCZDFLTS TYPE=CSECT, * LICENSE_HLQ=PKWARE.MVS * ***********************************************************
Remember that the PKWARE.MVS.INSTLIB(ACZDFLT) is a configuration member. Therefore, besides providing the high level qualifier for your installation, you can re-establish new defaults for ZIP and UNZIP processing. Below is an example that shows other parameters that can be coded.
*********************************************************** MCZDFLTS TYPE=CSECT, * LICENSE_HLQ=PKWARE.MVS * PARMLIB_DSNAME_ZIP=NULLFILE, * PARMLIB_DSNAME_UNZIP=NULLFILE, * ARCHIVE_UNIT=SYSDA, * TEMP_UNIT=SYSDA, * COMPRESSION_LEVEL=SUPERFAST, * CRLF=C * ***************** Bottom of Data **************************
Assembling Your Changes After editing the ASMDFLT member of PKWARE.MVS.INSTLIB, modify the ASMDFLT JCL member per your JCL Standards and submit the job to assemble PKWARE.MVS.INSTLIB(ACZDFLT) into PKWARE.MVS.LOAD. For every execution of ZIP and UNZIP, PKZIPz will refer to this assembled ACZDFLT module in your LOAD library.
Inputs
User inputs to PKZIPz can come from various sources and formats, as described in the following tables:
58
User Input Sources (MVS)
ACZDFLT or other customized defaults modules.
The installation defaults module, which is provided at installation time, or modified and re-assembled by the systems programmer responsible for installation changes.
Installation Configuration File A list of commands can be defined in a sequential file (or PDS member). This file can either be dynamically allocated (file name defined in ACZDFLT), or explicitly allocated through the //PARMLIB DD statement.
//SYSIN DD A batch, started-task or TSO user may provide this DD statement to input control statements.
EXEC PGM … PARM= A batch job or started task can pass a subset of parameters through the execution PARM= statement.
API Call Parm When calling PKZIPz from an application program, this set of parameters acts like EXEC PARM= above.
Processing Order of Control Statements In general, after the loading of the defaults module ACZDFLT, control statements are read sequentially from the various sources in the order below.
1. Configuration File (//PARMLIB DD or dynamically allocated).
2. EXEC PARM, or API Call Parm.
3. //SYSIN DD.
Exceptions to this order are for commands providing early initialization control through the EXEC PARM.
–DM ACZDFLT <= Defaults Module selection.
–ECHO.
Configuration Manager Processing: Managing Control Statements
Control Statement Definitions Control statements are managed via an internal control table, ACMTABLE. This table determines which command values are permitted for each command and provides validation information to the Configuration Manager.
Keywords, formats, and values generated in the defaults module are kept in synchronization with internal module control information maintained in ACMTABLE (which is used programmatically by Configuration Manager routines to parse control statements). The control statement values are mapped directly to the defaults module values for use.
Default values for the commands are held in module ACZDFLT, which is loaded at run time. A sample source module is provided (pkware.mvs.INSTLIB(ASMDFLT)) that can be assembled to change the defaults for the installation.
59
In addition, ACZDFLT can be assembled as a different load module name to create custom profiles of defaults for a variety of needs. A different flavor of ACZDFLT can be requested at execution time by using the JCL EXEC parameter –DM nnnnnnnn, where nnnnnnnn is the name of the module to use instead of ACZDFLT.
The ISPF interface has 2 options UD and ZD that allow you to see and set values for many of the commands. This may be used as a reference when trying to determine which of the available command values to use.
The batch SHOW_SETTINGS command may also be helpful as a reference to command names and their default values.
Troubleshooting
PKZIP and SecureZIP for z/OS Messages
PKZIPz writes messages to SYSPRINT (or other output DD file as specified by the defaults module) that indicate whether processing is successful. Each message type is defined with a unique message ID starting with “ZP” (see the Messages and Codes Guide for specific format information).
The volume of messages that are written to SYSPRINT is controlled by the command LOGGING_LEVEL. Additional processing information is displayed when VERBOSE is requested. This does not affect the output of critical error messages, which are written regardless of the level requested.
Explanatory information regarding messages can also be found on-line via the ISPF interface, or by browsing the PKWARE.MVS.HELP members.
Debugging Controls To see which processing options are in effect, code SHOW_SETTINGS as the last SYSIN command or EXE PARM to display all final parameter values.
When isses concerning non-VSAM data set allocation arise, specify TRACE_DYNALLOC(4) to see values used for individual files.
When issues concerning VSAM Cluster definitions arise, use TRACE_AMS(1) to see control cards passed to IDCAMS.
60
6 About Security, Certificates and Encryption
Requires SecureZIP
This chapter discusses how you utilize SecureZIP for z/OS to secure your data. Elements that are required to make a SecureZIP for z/OS archive are discussed in detail. These elements, when selectively used, combine to create a SecureZIP for z/OS archive or to allow the extraction of a file or files from a SecureZIP for z/OS archive.
A series of ISPF panels are used to assist you in building and maintaining the SecureZIP certificate store. These panels are standard with SecureZIP for z/OS. The chapter provides ISPF screens and SecureZIP commands used to accomplish these task, along with notes and comments.
Note: SecureZIP for z/OS is required for all certificate-based encryption operations, but PKZIP for z/OS Enterprise Edition can decrypt password-based archive data encrypted with SecureZIP.
Terms and Acronyms Used in This Chapter
SecureZIP for z/OS introduces new terminology to users that are familiar with PKZIP. These expressions relate to the security features in SecureZIP for z/OS.
Public Key Certificate(s)
Private Key Certificate(s)
Data Base Profile (Local Certificate Store)
LDAP Profile (Networked Certificate Store)
Password
RECIPIENT
MASTER RECIPIENT
Configuration Profile
Certificate Store
Common Name
61
Path
Cert Configuration
PING
TCPIP
User Certificate
Certificate Authority
Recipient DataBase
Recipient Searches
Filename Encryption
Authentication
File Signing
Archive Signing
Accessing Certificates
SecureZIP for z/OS provides access to certificates through a sets of local files, either sequential, PDS or PDSE, and VSAM index paths when control card requests are present.
In addition, RECIPIENT(LDAP"...) requests are resolved through configured network definitions.
The recipient of a file that has been encrypted with a public key must supply a matching private key to decrypt and UNZIP the file. This is done by using the RECIPIENT command to specify the location of the private-key certificate and the password required to access it. This password is unrelated to any password used to encrypt the file; it is used solely to access the recipient’s private key.
RECIPIENT commands may be included in the command input stream directly or through the INCLUDE_CMD command. A Private-Cert profile designates a saved repository of the private-key certificates. When SecureZIP for z/OS dialogs prepare batch JCL or UNZIP call streams, these commands will be automatically included when file decryption is requested.
Configuration Profile
A configuration profile is a collection of SecureZIP for z/OS commands that describes the SecureZIP environment. At execution time this profile is read to locate appropriate certificate stores and index. SecureZIP provides various means by which the configuration information can be supplied. Contact your organization’s technical support staff for instructions regarding access to the configuration.
62
Contents of the Configuration Profile Execution configuration values may be supplied in any of the following ways. It is highly recommended that the command sources be coordinated in logical groups (local certificate store settings or LDAP settings) so that overrides are not overly complex.
Direct commands in the SYSIN stream.
When accepted, these commands take precedence over other sources.
INCLUDE_CMD indirect reading of profile commands.
This is the method employed when you specify a file location through the SecureZIP Active DB Profile: field. When accepted, these commands take precedence over profiles read by the Defaults module, but may be overridden by SYSIN commands.
Defaults module indirect reading of profile commands.
This is the method employed when you specify UNDEFINED in the SecureZIP Active DB Profile: field.
Data Base (DB) Profile (Local Certificate Store) When you specify recipients for certificate-based encryption, SecureZIP for z/OS must be able to locate the recipients’ public-key certficates. One way to designate recipients is through the DB: form of the RECIPIENT command. This allows for recipient selection based on name or email address through a configured database of certificates on the system that is executing SecureZIP for z/OS.
Your organization’s technical support staff is responsible for configuring the local certificate store and should provide you with information on which profile data set—typically a member of a partitioned data set—to use. Below is a sample of the contents of the data base profile.
} Active Store Configuration: 'PKWARE.MVS.PROFILES(DBPROF)' -{CSPUB=4;1;PKWARE.MVS.CERTSTOR.PUBLIC} -{CSPRVT=4;1;PKWARE.MVS.CERTSTOR.PRIVATE} -{CSPUB_DBX=PKWARE.MVS.CERTSTOR.DBX} -{CSPUB_DBX_PATH_CN=PKWARE.MVS.CERTSTOR.PATHCN} -{CSPUB_DBX_PATH_EM=PKWARE.MVS.CERTSTOR.PATHEM} -{CSPUB_DBX_PATH_PUBKEY=PKWARE.MVS.CERTSTOR.PATHPUBK} -{CSCA=1;0;PKWARE.MVS.CERTSTOR.P7CA} -{CSROOT=1;0;PKWARE.MVS.CERTSTOR.P7ROOT} -{VALSIGN=TRUSTED,EXPIRED,NOTREVOKED} -{VALENCRYPT=TRUSTED,EXPIRED,NOTREVOKED} -{AUTHENTICATE=TRUSTED,EXPIRED,NOTREVOKED,TAMPERCHECK}
LDAP Profile (Networked Certificate Store) When you specify recipients for certificate-based encryption, SecureZIP for z/OS must be able to locate the recipients’ public-key certficates. One way to designate which recipients to include is through the LDAP interface to a directory server: form of the RECIPIENT command. This approach allows for recipient selection based on name, email address, or other installation-configured LDAP fields. One or more LDAP-compliant servers may be configured for searching.
63
The technical support staff responsible for configuring the LDAP compliant directory that stores certificates will provide you with information of which profile data set—typically a member of a partitioned data set—to use. Below is a sample of the contents of the file.
* ------------------------------------------------- * * zSeries LDAP access * * ------------------------------------------------- * * --- * Primary LDAP * --- -{LDAP=1;192.168.9.12;389;0;0;;;*EMAIL;| o=pkware,c=US,cn=user,dc=cosmos,dc=pkzip,dc=com} * ---
Note: The LDAP profile may not contain any encryption certificate validation policies. If the end user specifies only the LDAP profile without a local certificate store, then the SecureZIP default validation settings of TRUSTED and REVOKED will be enforced for the run. This will cause the job to fail during validation of the trusted certificate path because there are no CA and/or root certificates available for processing. If you wish to execute the SecureZIP job with the LDAP profile only, then you must include the validation policy in the job stream (see sample below), or add the VALENCRYPT policy statement to the LDAP profile.
-INCLUDE_CMD(PKWARE.MVS.PROFILES(LDAP)) -RECIPIENT(LDAP:CN=PKWARE TEST4,R) -{VALENCRYPT=NOTTRUSTED,EXPIRED,NOTREVOKED}
Recipient Searches When RECIPIENT requests are made for either the local certificate store ("DB:"), an LDAP directory ("LDAP:") or both ("SYSTEM:"), a set of search criteria are provided. The search criteria of Email address ("EM=" or "mail=") and Common Name ("CN=") are accepted by both the DB: and LDAP: service providers.
When multiple RECIPIENT requests are made, two or more search criteria may resolve to the same recipient certificate. For example, if both EM= and CN= are used in different RECIPIENT (or MASTER_RECIPIENT, contingency key processing) requests, both may find the same public key certificate. The first entry found will be used, and any duplicate copies of the same certificate will be ignored, resulting in only one representation of the certificate.
A search for an individual by name or email address may return multiple digital certificates, whether from the same certificate store source or not. In this case, more than one representation of an individual can be included in the run.
LDAP searching can be accomplished with direct RECIPIENT requests:
-RECIPIENT(LDAP:search_criteria)
or implicitly:
-RECIPIENT(*system:search_criteria).
In either case, the certificate store configuration settings define the order in which the LDAP servers are searched. However, in the case of using *system, local certificate stores are searched prior to any of the configured LDAPs.
64
When multiple stores are to be searched (*system: or LDAP:), all RECIPIENT requests are searched in one store before the next store is referenced. If a RECIPIENT request finds one or more entries in one store, subsequent stores are not searched. This means that it is possible for generic LDAP search criteria to bypass entries defined in subsequent LDAP servers. RECIPIENT requests that were not satisfied at all by the higher-level store search continue to be searched for.
Example: Search LDAP’s for RECIPIENT matches
LDAP #1 0 entries 0 matches
LDAP #2 3 entries 3 matches
Add entry LDAP #1 has an entry added matching RECIPIENT
LDAP #1 1 entry 1 match
LDAP #2 3 entries 0 matches
Local Certificate Stores
Access x.509 Public and Private Key Certificates See also Chapter 2 for an overview of certificate stores.
SecureZIP for z/OS introduces a new subtask, CSERV, that utilizes RSA’s BSAFE Cert-C Toolkit to access X.509 public- and private-key certificates. The access to the various certificate stores by this task is governed by various forms of the RECIPIENT, SIGN_ARCHIVE, SIGN_FILES and AUTHCHK commands, as well as by a suite of configuration commands.
The configuration commands are read either through SYSIN, INCLUDE_CMD(parmlib) or SECUREZIP_CONFIG specifications.
The syntax of the commands is -{ ... }. The semi-colon (;) is used as a parameter delimiter.
-{CSPUB=type;Seq;string PUB} -{CSPRVT=type;Seq;string Prvt} -{CSCA=type;Seq;string CA} -{CSROOT=type;Seq;string Root} -{CSPUB_DBX=vsam_cluster_base_index} -{CSPUB_DBX_PATH_CN=vsam_path_through_AIX_for_Common_Name} -{CSPUB_DBX_PATH_EM=vsam_path_through_AIX_for_Email_address} -{CSPUB_DBX_PATH_PUBKEY=vsam_path_through_AIX_for_PublicKey} -{AUTHENTICATE=TRUSTED,EXPIRED,REVOKED,TAMPERCHECK} -{VALSIGN=TRUSTED,EXPIRED,NOTREVOKED} -{VALENCRYPT=TRUSTED,EXPIRED,NOTREVOKED} -{RESET}
Where:
type (*PATH 0) (FILE 1) (*DB 2) (*LDAP 3) (*PDS 4)
Seq 0 through 9 (Cert Store search order)
LDAP - timeout of 0 results in system settings
65
user of NULL or ";;" will use "anonymous" login
Certificate Store References –{CSxxx}
If not supplied through configuration changes, the defaults are:
{CSPUB=1;9;DUMMY} {CSPRVT=1;9;DUMMY} {CSCA=1;9;DUMMY} {CSROOT=1;9;DUMMY} {CSPUB_DBX=SECZIP.CERTSTOR.PUBLIC.DBX} {CSPUB_DBX_PATH_CN=SECZIP.CERTSTOR.PATHCN} {CSPUB_DBX_PATH_EM=SECZIP.CERTSTOR.PATHEM} {CSPUB_DBX_PATH_PUBKEY=SECZIP.CERTSTOR.PATHPUBK}
The local zSeries certificate store for public-key certificates (configuration settings for {CSPUB_...}), can be built as a PDS[E] indexing scheme for common name and email address searches. This is accomplished through a VSAM base cluster and a set of alternate index paths to access the appropriate field types.
The PDS[E] and the VSAM suite are managed as a unit and should not be manipulated independently from the supplied SecureZIP utilities. When no public-key store (CSPUB=) PDS[E] is specified, then the indexing (CSPUB_DBX...) files are not accessed.
The CSCA (Certificate Authority) and CSROOT (Trusted Root Certificate Authority) certificates are maintained in repective sequential files in X.509 PKCS#7 format.
Overrides to {CSxxx…} or {LDAP…} configuration commands can be done through input command streams or included members. However, you must take care to coordinate overrides so that intermixed PATHS do not result in different databases or indexes being used when resolving the various search criteria.
Authentication and Certificate Validation Policies Certificate validation may be done when activities in the following functional areas are performed:
Recipient based encryption
Archive or file signing
Authentication of digital signatures for files and/or archive directory
Validation policies are passed to SECZIP and SECUNZIP to govern various aspects of certificate validation at execution time. The policies are defined in configuration profile settings and may also be included as override commands for individual executions of SECZIP and SECUNZIP.
The policy command settings are coded in the same format as other certificate store profile commands, with the syntax -{...}
Each functional area supports a single policy statement with its associated settings. The CERTSTORE Policy Setup panel will generate a policy statement for each functional area for use in the certificate store profile.
66
-{AUTHENTICATE=...}
-{VALENCRYPT=...}
-{VALSIGN=...}
{AUTHENTICATE} Policy
The {AUTHENTICATE} setting can be used within an include member that contains configuration commands, or within the standard command stream. It defines the level of processing that AUTHCHK commands will perform. The last AUTHENTICATE command found in the input stream will be used for processing and fully defines the signature authentication elements to be verified. The default settings may be changed by the SecureZIP administrator at any time. However, if this command is not supplied, all supported elements default to being checked.
–{AUTHENTICATE=[ALL]|[NOT]EXPIRED,[NOT]TRUSTED,[NOT] REVOKED,[NO]TAMPERCHECK}
The AUTHENTICATE policy setting is usually located in the local certificate store configuration file supplied by the SecureZIP administrator. If no explicit setting is present, AUTHENTICATE=ALL is the default. Although multiple AUTHENTICATE policy command sequences may be entered, the sub-parameter values are not cumulative across commands. The latest entry of AUTHENTICATE= encountered in the command stream takes effect.
ALL - This sub-parameter activates all levels of authentication. If followed by negating sub-levels, then all but those negating levels are activated. For example:
-{AUTHENTICATE=ALL,NOTEXPIRED}
means that expired certificates will not cause an authentication error, but TRUST and TAMPERCHECK must both be satisfied.
If “ALL” is not present in the command syntax, a missing sub-parameter is reset to the “NO/NOT” state. Each sub-policy to be checked must be listed in its positive form.
For example: {…=NOTEXPIRED,TRUSTED} results in NOTREVOKED and NOTAMPERCHECK, whereas {…=ALL,NOTEXPIRED,TRUSTED} results in REVOKED and TAMPERCHECK.
[NO]TAMPERCHECK – The signature associated with the archive or file(s) involved will be used to verify that the content has not been altered since the archive was built.
[NOT]EXPIRED – The digital certificates used to originally perform the signing operation contain internal date ranges of validity. The AUTHCHK operation will fail if any of the certificates in the trust chain are not found to be within their stated data range. Note that an end-certificate may have expired at the time that the archive is being accessed, and NOTEXPIRED may be used to continue processing.
[NOT]REVOKED – A certificate owner may request that the issuing certificate authority declare a certificate to be revoked and thereby no longer consider that certificate to be valid. The AUTHCHK operation will fail if any of the certificates in the trust chain are found to have been revoked or if the revocation status could not be determined.
[NOT]TRUSTED – Each end-certificate used in the signature must be traced back to a trusted root certificate. The CACA and CSROOT stores on the local system performing
67
the authentication check will be accessed to determine if the entire certificate chain can be trusted. Although the Root (“self-signed”) certificate may be included within the archive, it MUST also exist in the CSROOT store to complete the TRUSTED state.
{VALSIGN} Policy
The {VALSIGN} setting can be used within an include member that contains configuration commands, or within the standard command stream. It defines the level of processing that SIGN_FILES and SIGN_ARCHIVE commands will perform during SECZIP execution. The last VALSIGN command found in the input stream will be used for processing and fully defines the signing certificate elements to be verified. The default settings may be changed by the SecureZIP administrator at any time. However, if this command is not supplied, all supported elements default to being checked.
–{VALSIGN=[ALL]|[NOT]EXPIRED,[NOT]TRUSTED,[NOT]REVOKED}
The VALSIGN policy setting is usually located in the local certificate store configuration file supplied by the SecureZIP administrator. If not present, VALSIGN=ALL is the default. Although multiple VALSIGN policy command sequences may be entered, the sub-parameter values are not cumulative between commands. The latest entry of VALSIGN= encountered in the command stream takes effect.
ALL - This sub-parameter activates all levels of validation. If followed by negating sub-levels, then all but those negating levels are activated. For example:
-{VALSIGN=ALL,NOTEXPIRED}
means that expired certificates will not cause an signing error, but TRUST must be satisfied.
If “ALL” is not present in the command syntax, a missing sub-parameter is reset to the “NO/NOT” state. Each sub-policy to be checked must be listed in its positive form.
For example: {…=NOTEXPIRED,TRUSTED} results in NOTREVOKED, whereas {…=ALL,NOTEXPIRED,TRUSTED} results in REVOKED.
[NOT]EXPIRED – The digital certificates used to originally perform the signing operation contain internal date ranges of validity. The SIGN operation will fail if any of the certificates in the trust chain are not found to be within their stated data range. Note that an end-certificate may have expired at the time that the archive is being accessed, and NOTEXPIRED may be used to continue processing.
[NOT]REVOKED – A certificate owner may request that the issuing certificate authority declare a certificate to be revoked and thereby no longer consider that certificate to be valid. The SIGN operation will fail if any of the certificates in the trust chain are found to have been revoked or if the revocation status could not be determined.
[NOT]TRUSTED – Each end-certificate used in the signature must be traced back to a trusted root certificate. The CACA and CSROOT stores on the local system performing the authentication check will be accessed to determine if the entire certificate chain can be trusted. Although the Root (“self-signed”) certificate may be included within the archive, it MUST also exist in the CSROOT store to complete the TRUSTED state.
68
{VALENCRYPT} Policy
The {VALENCRYPT} setting can be used within an include member that contains configuration commands, or within the standard command stream. It defines the level of processing that RECIPIENT-based encryption requests will perform during SECZIP execution. The last VALENCRYPT command found in the input stream will be used for processing and fully defines the signing certificate elements to be verified. The default settings may be changed by the SecureZIP administrator at any time. However, if this command is not supplied, all supported elements default to being checked.
–{VALENCRYPT=[ALL]|[NOT]EXPIRED,[NOT]TRUSTED,[NOT]REVOKED}
The VALENCRYPT policy setting is usually located in the local certificate store configuration file supplied by the SecureZIP administrator. If not present, VALENCRYPT=ALL is the default. Although multiple VALENCRYPT policy command sequences may be entered, the sub-parameter values are not cumulative between commands. The latest entry of VALENCRYPT= encountered in the command stream takes effect.
ALL - This sub-parameter activates all levels of validation. If followed by negating sub-levels, then all but those negating levels are activated. For example:
-{VALENCRYPT=ALL,NOTEXPIRED}
means that expired certificates will not cause an encryption error, but TRUST must be satisfied.
If “ALL” is not present in the command syntax, a missing sub-parameter is reset to the “NO/NOT” state. Each sub-policy to be checked must be listed in its positive form.
For example: {…=NOTEXPIRED,TRUSTED} results in NOTREVOKED, whereas {…=ALL,NOTEXPIRED,TRUSTED} results in REVOKED.
[NOT]EXPIRED – The digital certificates used to originally perform the signing operation contain internal date ranges of validity. The RECIPIENT encryption operation will fail if any of the certificates in the trust chain are not found to be within their stated data range. Note that an end certificate may have expired at the time that the archive is being accessed. NOTEXPIRED may be used to continue processing.
[NOT]REVOKED – A certificate owner may request that the issuing certificate authority declare a certificate to be revoked and thereby no longer consider that certificate to be valid. The RECIPIENT ENCRYPTION operation will fail if any of the certificates in the trust chain are found to have been revoked or if the revocation status could not be determined.
[NOT]TRUSTED – Each end-certificate used in the signature must be traced back to a trusted root certificate. The CACA and CSROOT stores on the local system performing the authentication check will be accessed to determine if the entire certificate chain can be trusted. Although the root (“self-signed”) certificate may be included within the archive, it must also exist in the CSROOT store to complete the TRUSTED state.
69
Other Profile Commands
{RESET} Clearing the Active Configuration
The {RESET} command can be used at the beginning of an include member that contains configuration commands, or within the standard command stream to “clear” all existing {CSxxx…} and {LDAP…} configuration commands that may have been previously loaded. This will help avoid mixed entries if an incomplete set of overrides is present. Remember that the defaults module may include settings for the configuration commands even if commands are not explicitly coded at run-time. The default settings may be changed by the SecureZIP administrator at any time.
FACILITY Designations for Cryptographic Services
The selection of which cryptographic facilities are to be used for various security functions is controlled through individual command settings.
See: FACILITY_ENCRYPTDATA, FACILITY_HASH, FACILITY_RANDOM.
Execution Time SecureZIP for z/OS is commonly run as a batch job step utility to place one or more files into a SecureZIP container (archive) prior to subsequent processing (such as transporting to an off-board system). Processing considerations when utilizing recipient-based encryption include:
Using INCLUDE_CMD to reference the local certificate store configuration control records (created by the initial setup in Certificate Store Administration) in the SYSIN command stream
Using the RECIPIENT command to trigger certificate-based encryption. (Optionally, the RECIPIENT command used for extraction (decryption) may be referenced via INCLUDE_CMD to protect the password information contained within it.)
Having dataset-level READ authority (via RACF or equivalent product) to the private-key certificate and referenced command files necessary to access the certificate
Performing JCL return code checking within the job stream after the SECZIP program has completed to test the success of Encryption/Decryption processing
Security Considerations To ensure the continued integrity of private-key certificates within an organization, special attention should be paid to protecting access to them.
The X.509 PKCS#12 certificate format supported by SecureZIP has an inherent security mechanism designed to protect the private keys within the transportable certificate by way of an access password. This means that, without the appropriate password, the private keys cannot be accessed from the private-key PKCS#12 digital certificate (on any system or location).
RACF READ authority (or equivalent) must be granted to the job accessing certificate store, X.509 certificate file and the referenced input stream containing the command having the certificate request (and password for a private-key certificate).
70
To perform a decryption operation, SecureZIP for z/OS requires read access to the PKCS#12 private-key certificate (file or PDS member), as well as a command (RECIPIENT) containing the corresponding password. Similarly, the signing and authentication commands (SIGN_ARCHIVE, SIGN_FILES and AUTCHK) may reference private keys. The following should be considered when using SecureZIP to access private keys:
Password information will be masked out in SecureZIP SYSPRINT output.
If jobstream inputs can be viewed by operational staff members, then an indirect reference to the command(s) containing the password should be considered.
Read protection of command files containing passwords
Read protection of PKCS#12 certificate files
Optionally use ECHO=N within the command sequence to eliminate the command from showing in the SYSPRINT output.
SecureZIP Certificate Store Administration and Configuration For detailed instructions on certificate store configuration and management, LDAP configuration, and other x.509 certificate utilities, see the SecureZIP for z/OS System Administrator’s Guide.
Run-Time Configuration
The Runtime Configuration panel is used for entering configuration information for the ISPF SecureZIP interface (option C). That information includes active load library, default options files, job card and other miscellaneous information.
A panel for SecureZIP certificate store settings must be configured as well. A message at the bottom of the configuration panel directs you to press “Enter” to view the SecureZIP certificate store settings.
Runtime Configuration Panel
SecureZIP Runtime Configuration OPTION ===> More: - Initial Execution Default Command Settings Defaults module.....: ACZDFLT (ACZDFLT) ZIP processing......: 'PKWARE.MVS.INSTLIB(CMDZIP)' UNZIP processing....: 'PKWARE.MVS.INSTLIB(CMDUNZIP)' Foreground Processing Controls Use TSO Prefix : N (Y/N) Lowest Acceptable RC: 4 (0,4,8) SYSPRINT Allocation Type : CYLS (BLKS,TRKS,CYL) Primary : 3 Secondary : 1
71
Batch Job Card information //FPDCS1 JOB 'ACCOUNTING INFO',CLASS=A,REGION=8M, // MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID //* Hit ENTER for SecureZIP Certificate Store Settings To EXIT Press PF3 For HELP Press PF1
Runtime Configuration Panel: Certificate Stores
SecureZIP Runtime Configuration Option ===> Certificate Store Settings ( ENTER to validate PF7/PF8 to scroll) / to Edit the file M to Display a member selection list Private-Cert > 'PKWARE.MVS.JCL(CERTPROF)' DB Profile > 'PKWARE.MVS.PROFILES(DB810X)' LDAP Profile > 'PKWARE.MVS.JCL(LDAPFPD1)' ZIP Recipient List > 'PKWARE.MVS.CERTSTOR.PROFILES($RECIPS)' UNZIP Recipient List> UNDEFINED Archive Signing > 'PKWARE.MVS.CERTSTOR.PROFILES($SIGNARC)' File Signing > 'PKWARE.MVS.CERTSTOR.PROFILES($SIGNFIL)' Authenticate Archive> 'PKWARE.MVS.CERTSTOR.PROFILES($AUTHARC)' Authenticate Files > 'PKWARE.MVS.CERTSTOR.PROFILES($AUTHFIL)' Authenticate Files > 'PKWARE.MVS.CERTSTOR.PROFILES($AUTHFIL)' ------------------------------------------------------------------------------- ***** Top of Data ************************************************************** Private-key Certificate Recipient(s): ===================================== *---------------------------------------------------------------------* * Profile PKWARE.MVS.JCL(certprof) * *---------------------------------------------------------------------* *-recipient(db:cn=PKWARE TEST1,R,PASSWORD=PKWARE) *-recipient(dsn://'SECZIP.IVP.CERT.ADMIN04.PFX',password=password) Local Certificate Store DB Profile: ============================== *** * LOCAL CERTIFICATE STORE CONFIGURATION CONTROL * * Include this member in SecureZIP runs requiring Local Certificate * Store RECIPIENTS, SIGN_ARCHIVE, SIGN_FILES and AUTHCHK signatories. *** -{CSPUB=4;1;PKWARE.MVSSTD.CERTSTOR.PUBLIC} -{CSPRVT=4;1;PKWARE.MVSSTD.CERTSTOR.PRIVATE} -{CSPUB_DBX=PKWARE.MVSSTD.CERTSTOR.DBX} -{CSPUB_DBX_PATH_CN=PKWARE.MVSSTD.CERTSTOR.PATHCN} -{CSPUB_DBX_PATH_EM=PKWARE.MVSSTD.CERTSTOR.PATHEM} -{CSPUB_DBX_PATH_PUBKEY=PKWARE.MVSSTD.CERTSTOR.PATHPUBK} -{CSCA=1;0;PKWARE.MVSSTD.CERTSTOR.P7CA} -{CSROOT=1;0;PKWARE.MVSSTD.CERTSTOR.P7ROOT} -{AUTHENTICATE=TRUSTED,EXPIRED,REVOKED,TAMPERCHECK} *{VALSIGN=TRUSTED,EXPIRED,REVOKED} *{VALENCRYPT=TRUSTED,EXPIRED,REVOKED} LDAP Configuration Profile: =========================== -{LDAP=1;ASI4;4389;0;0;;;*CN;o=PKWARE} Saved Recipient List: ===================== *RECIPIENT(DB:CN=PKWARE Test1,PASSWORD=PKWARE)
72
Saved Archive Signing List: =========================== -SIGN_ARCHIVE(DB:CN=PKWARE Test1,PASSWORD=PKWARE) Saved File Signing List: ======================== -SIGN_FILES(DB:CN=PKWARE Test1,PASSWORD=PKWARE) -SIGN_FILES(DB:CN=PKWARE Test2,PASSWORD=PKWARE) -SIGN_FILES(DB:CN=PKWARE Test3,PASSWORD=PKWARE) -SIGN_FILES(DB:CN=PKWARE Test4,PASSWORD=PKWARE) Saved Archive Authentication List: ================================== -AUTHCHK(ARCHIVE,DB:CN=PKWARE Test1) Saved File Authentication List: =============================== 1AUTHCHK(FILES,DB:CN=PKWARE Test1,PASSWORD=PKWARE) -SIGN_FILES(DB:CN=PKWARE Test4,PASSWORD=PKWARE) Saved Archive Authentication List: ================================== -AUTHCHK(ARCHIVE,DB:CN=PKWARE Test1) Saved File Authentication List: =============================== -AUTHCHK(FILES,DB:CN=PKWARE Test1) ***** Bottom of Data *******************************************
The preceding panel is used for entering configuration information for certificate profiles and for editing saved control cards used in certificate processing.
That information includes the locations of the private-key certificate, the data base profile, and the LDAP profile. You must specify the location of private-key certificates. For the locations of the DB and/or LDAP profiles, contact your SecureZIP administrator.
SecureZIP Runtime Configuration Panel Undefined
SecureZIP Runtime Configuration Option ===> Certificate Store Settings ( ENTER to validate PF7/PF8 to scroll) / to Edit the configuration file M to Display a member selection list Private-Cert> undefined DB Profile > undefined LDAP Profile> undefined / to Edit the saved lists Zip Recipient List > undefined UNZIP Recipient List> UNDEFINED Archive Signing > undefined File Signing > undefined Authenticate Archive> undefined Authenticate Files > undefined ***** Top of Data ************************************************************** Private-key Certificate Recipient(s): ===================================== Profile: MISSING DATASET NAME Local Certificate(DB) Profile: ==============================
73
Profile: MISSING DATASET NAME LDAP Configuration Profile: =========================== Profile: MISSING DATASET NAME ***** Bottom of Data ***********************************************************
As you begin the process of creating archives with recipients and signing and validate existing archives, the Edit/Saved Lists are populated with control records.
SecureZIP Runtime Configuration Panel with DB Profile Defined The following example shows how the Runtime Configuration Panel looks after completing the local certificate store configuration.
SecureZIP Runtime Configuration Option ===> Certificate Store Settings ( ENTER to validate PF7/PF8 to scroll) / to Edit the configuration file Private-Cert> undefined DB Profile > 'PKWARE.MVS.JCL(CCFGFPD1)' LDAP Profile> undefined / to Edit the saved lists Recipient List > undefined Archive Signing > undefined File Signing > undefined Authenticate Archive> undefined Authenticate Files > undefined ***** Top of Data ************************************************************** Private-key Certificate Recipient(s): ===================================== Profile: Undefined Local Certificate(DB) Profile: ============================== * DATABASE ACCESS CONTROL CARDS -{CSPUB=4;1;PKWARE.MVS1.CERTSTOR.PUBLIC} -{CSPRVT=4;1;PKWARE.MVS1.CERTSTOR.PRIVATE} -{CSPUB_DBX=PKWARE.MVS1.CERTSTOR.DBX} -{CSPUB_DBX_PATH_CN=PKWARE.MVS1.CERTSTOR.PATHCN} -{CSPUB_DBX_PATH_EM=PKWARE.MVS1.CERTSTOR.PATHEM} -{CSPUB_DBX_PATH_PUBKEY=PKWARE.MVS1.CERTSTOR.PATHPUBK}
SecureZIP Runtime Configuration Panel with Private Certificate Location The following example shows the Runtime configuration panel with the private certificate identified that will be used to provide the private key to decrypt an archive. Notice that the RECIPIENT location, the requirement to always find the certificate (R), and the password for the private key are displayed as part of the panel information provided.
The private certificate dataset must be allocated and specified by the user as it is not automatically generated during the installation process. Be sure to require suitable security authority for any and all datasets that contain private certificate password information.
74
SecureZIP Runtime Configuration Option ===> Certificate Store Settings ( ENTER to validate PF7/PF8 to scroll) / to Edit the configuration file Private-Cert> ‘PKWARE.MVS.JCL(CERTPROF)' DB Profile > 'PKWARE.MVS.JCL(CCFGFPD1)' LDAP Profile> 'PKWARE.MVS.JCL(LDAPFPD1)' / to Edit the saved lists Recipient List > undefined Archive Signing > undefined File Signing > undefined Authenticate Archive> undefined Authenticate Files > undefined ***** Top of Data ************************************************************** Private-key Certificate Recipient(s): ===================================== *---------------------------------------------------------------------* * Profile PKWARE.MVS.JCL(CERTPROF) * *---------------------------------------------------------------------* -recipient(db:cn=PKWARE TEST1,R,PASSWORD=xxxxxxxx)
Filename Encryption
How SecureZIP for z/OS Encrypts File Names SecureZIP for z/OS encrypts file names using your current settings for (strong) encryption method and algorithm. File names can be encrypted using either strong password encryption or a recipient list (or both).
Note: Encrypting names of files and folders in an archive encrypts and hides a good deal of other internal information about the archive as well. To encrypt file names, SecureZIP for z/OS encrypts the archive's central directory, where virtually all such metadata about the archive is stored.
Note: Be aware that archive comments are not encrypted even when you encrypt file names. Do not put sensitive information in an archive comment.
When SecureZIP for z/OS Encrypts File Names With archives that do not already contain encrypted file names:
SecureZIP for z/OS encrypts file names only when you add files to an archive. SecureZIP for z/OS does not encrypt file names when you encrypt files that are already in an archive even if the option to encrypt file names is turned on.
SecureZIP for z/OS encrypts file names only when you add and encrypt files. SecureZIP for z/OS does not encrypt file names when you add files without encrypting them, even if the option to encrypt file names is turned on.
Encrypting File Names When You Update an Archive If you turn on the setting to encrypt file names and then add files to an archive that already contains files with unencrypted file names, SecureZIP for z/OS encrypts the names of all files in the archive.
75
If the archive contains files whose contents are already encrypted, SecureZIP for z/OS rejects an attempt to add filename encryption.
If you update an archive that already contains files with encrypted file names, SecureZIP for z/OS encrypts the newly added files and their names using the same password or recipient list originally used to encrypt file names in the archive.
Notes:
Once file names in an archive are encrypted, you cannot currently remove the encryption or change the password or recipient list used.
You cannot change the encryption on files that are already in an archive that contains encrypted file names.
Opening and Viewing an Archive That Has Encrypted File Names An archive that contains encrypted file names requires SecureZIP for zSeries 8.x or SecureZIP for z/OS to open it.
Input Required To View Recipients in a Filename Encrypted Archive To view the recipients of a filename-encrypted archive, place VERBOSE in the input.
//FPDTEST3 JOB '0',CLASS=A,REGION=64M, // MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID //UNZIP EXEC PGM=PKUNNZIP //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD // DD DISP=SHR,DSN=PKWARE.MVS.LOAD //CERT DD DSN=FPD.FPDPVT08.PFX,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKWARE.MVS.FNEREC.ZIP) -VERBOSE -ACTION(VIEW) -RECIPIENT(DD:CERT,R,PASSWORD=PKWARE)
View of Recipients in a Filename Encrypted Archive
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 -INCLUDE_CMD=PKZIP.IVP.JCL(DEVCERT1) -ECHO=N -ARCHIVE_DSN(PKWARE.MVS.FNEREC.ZIP) -VERBOSE -LOGGING_LEVEL(VERBOSE) -ACTION(VIEW) -RECIPIENT(DD:CERT,R,PASSWORD=******) ZPCM011I Processing EXEC PARM parameters ZPEN110I Locating Digital Certificates ... ZPCM023I Digital Certificate Store Configuration {CSPUB=4;1;PKWARE.MVS.CERTSTOR.PUBLIC} {CSPRVT=4;1;PKWARE.MVS.CERTSTOR.PRIVATE} {CSCA=1;1;PKWARE.MVS.CERTSTOR.PUBLIC(CAP7)}
76
{CSROOT=1;1;PKWARE.MVS.CERTSTOR.PUBLIC(ROOTP7)} {CSPUB_DBX=PKWARE.MVS.CERTSTOR.PUBLIC.DBX} {CSPUB_DBX_PATH_CN=PKWARE.MVS.CERTSTOR.PATHCN} {CSPUB_DBX_PATH_EM=PKWARE.MVS.CERTSTOR.PATHEM} {CSPUB_DBX_PATH_PUBKEY=PKWARE.MVS.CERTSTOR.PATHPUBK} {LDAP=1;192.168.0.54;4389;1;0;CN=LDAP Administrator;secret;;O=PKWARE;} ZPCM023C --------------------------------------- ZPCM024I Digital Certificate Request List ZPCM024C Req'd Private Recipient dd:CERT ZPCM024C FILE FOUND *REQUIRED* ZPCM024C -------------------------------- ZPAP900I NO API REQUIRED ZPCM100I Configuration Manager Shutdown. Posting Main Task: 00000000 ZPAM030I INPUT Archive opened: PKWARE.MVS.FNEREC.ZIP ZPAM710I Archive Directory is Compressed 85% ZPAM711I Archive Directory is Encrypted: AES_256 Certificate Only ZPEX100I Extract Task { 5} TCB: 008D0A90 Started. ZPEX004I Archive Central Directory extracted for processing. ZPAM014I 234 file(s) are in the input Archive. ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE ZPAM013I ********************************************************************************* ZPAM015I Length Method Size Ratio Date Time CRC-32 Name ZPAM016I ------------- ------------ ------------- ----- ---------- ----- -------- ----------------------------------- ZPAM017I 4,183 Deflate-SFST 2,240 46% 08/30/2005 16:24 419ABFDA ! PKZIP/FPD/JCL/ACZDFLT ZPAM017I 4,183 Deflate-SFST 2,256 46% 08/30/2005 16:24 18A324CE ! PKZIP/FPD/JCL/ACZDFL ZPAM017I 1,067 Deflate-SFST 1,536 0% 08/30/2005 16:24 183003D8 ! PKZIP/FPD/JCL/ZIPVIEW ………………… ………………… …………… ZPAM017I 1,067 Deflate-SFST 1,536 0% 08/30/2005 16:24 2F3E1C63 ! PKZIP/FPD/JCL/ZIP12 ZPAM017I 985 Deflate-SFST 1,520 0% 08/30/2005 16:24 5A8D5879 ! PKZIP/FPD/JCL/ZIP123 ZPAM018I ------------- ------------- ----- ZPAM019I 698,546 450,288 36% ZPAM013I ********************************************************************************* ZPAM140I FILES: VIEWED EXCLUDED BYPASSED IN ERROR ZPAM140I 234 0 0 0 ZPAM712I Archive Directory Encryption Recipients: ZPAM320I 4 recipient(s) were designated: ZPAM321I Recipient: PKWARE Test0 ZPAM323I Email: [email protected] ZPAM325I Valid: 07/23/2002-07/23/2003 ZPAM326I Issuer: VeriSign, Inc. ZPAM321I Recipient: PKWARE TEST1 ZPAM323I Email: [email protected] ZPAM325I Valid: 11/05/2003-11/04/2004 ZPAM326I Issuer: VeriSign, Inc. ZPAM321I Recipient: PKWARE Test2 ZPAM323I Email: [email protected] ZPAM325I Valid: 07/22/2003-07/21/2004 ZPAM326I Issuer: VeriSign, Inc. ZPAM321I Recipient: PKWARE Test00 ZPAM323I Email: [email protected] ZPAM325I Valid: 07/22/2003-07/21/2004 ZPAM326I Issuer: VeriSign, Inc. ZPAM101I Archive Manager Task { 3} TCB: 008D0E88 shutdown begun. ZPAM109I Archive Manager Task { 3} TCB: 008D0E88 shutdown complete. ZPEX101I Extract Task { 5} TCB: 008D0A90 shutdown begun. ZPEX109I Extract Task { 5} TCB: 008D0A90 shutdown complete. ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
77
View Detail of an Archive that Has Encrypted File Names ZPAM711I in the output below identifies the type of encryption used for filename encryption.
ZPAM030I INPUT Archive opened: PKWARE.MVS.FNEREC.ZIP ZPAM710I Archive Directory is Compressed 85% ZPAM711I Archive Directory is Encrypted: AES_256 Certificate Only ZPAM014I 234 file(s) are in the input Archive. ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE ZPAM013I ************************************************************* ZPAM001I Filename: PKZIP/FPD/JCL/ACZDFLT ZPAM002I File type: TEXT ZPAM003I Date/Time: 30-AUG-2005 16:24:00 ZPAM004I Compression Method: Deflate- Super Fast ZPAM005I Compressed Size: 2,240 ZPAM006I Uncompressed Size: 4,183 ZPAM007I 32-bit CRC: 419ABFDA LHDR Offset: 0 ZPAM008I Created by: PK zSeries 9.0 ZPAM009I Needed to extract: ZipSpec 6.1 ZPAM010I Encryption: AES_256 Certificate Key BSAFE(R) ZPAM301I File Type: NONVSAM PDS ZPAM302I File PDS Directory Blocks: 50 ZPAM303I File Record Format: FB ZPAM304I File Allocation Type: CYL ZPAM305I File Primary Space Allocated: 5 ZPAM306I File Secondary Space Allocated: 9 ZPAM307I File Record Size: 80 ZPAM308I File Block Size: 27920 ZPAM309I File Volume(s) Used: FPD002 ZPAM310I File Creation Date: 2005/07/22 ZPAM311I File Referenced Date: 2005/08/30 ZPAM319I SMS Storage Class: PRIVATE ZPAM312I File PDS Extended Directory Information: DIRECTORY INFORMATION FOLLOWS LENGTH=00001E 000000 01040029 0102198F 0102205F 14010033 |........... ....| ) _ 3| 000010 00330000 C6D7C440 40404040 40400000 |....FPD ..| 3 @@@@@@@ | ZPAM312C -SIZE -CREATED-- ------CHANGED------ ---ID-- -INIT VV.MM ZPAM312C 51 2002/07/17 2002/07/24 14:01:29 FPD 51 01.04 ZPAM313I PDS member TTRKZC: 00010700000F ZPAM320I 4 recipient(s) were designated: ZPAM321I Recipient: PKWARE Test2 ZPAM322I Public Key Hash: 07E091CE30862B61663CF9D356863BF84D3DC8D5 ZPAM323I Email: [email protected] ZPAM324I Cert: //'PKWARE.MVS.CERTSTOR.PRIVATE(PKT2005)' ZPAM321I Recipient: PKWARE Test2 ZPAM322I Public Key Hash: 271842663AA344FBC35656BE68B5A46EE7E545F0 ZPAM323I Email: [email protected] ZPAM324I Cert: //'PKWARE.MVS.CERTSTOR.PUBLIC(PKT2003)' ZPAM321I Recipient: PKWARE TEST1 ZPAM322I Public Key Hash: 5D9E8B89B5948E9E853338A7250D64C5BED5E9E7 ZPAM323I Email: [email protected] ZPAM324I Cert: //'PKWARE.MVS.CERTSTOR.PUBLIC(PKT12003)' ZPAM321I Recipient: PKWARE Test00 ZPAM322I Public Key Hash: 6E16CFEFFAA093242B89DEE623C7D7428082F3E3 ZPAM323I Email: [email protected] ZPAM324I Cert: //'PKWARE.MVS.CERTSTOR.PUBLIC(PK002003)' ZPAM013I *************************************************************
Two fields in the preceding output require explanation:
Created by: Lists the program, and its release level, that created the archive.
Needed To Extract: Lists the version of the ZIP file format specification on which the program that created the archive is based.
78
The number listed is not a version of the SecureZIP for z/OS program. It is the earliest version of the ZIP file format specification that defines certain features implemented in the program. A different program must support at least the listed version of the ZIP file format in order to extract files from an archive that uses features initially defined in the listed specification.
For example, to extract files from an archive that uses filename encryption, a program must support a version of the ZIP file format that provides for filename encryption.
Decrypting a Filename-Encrypted Archive When opening an archive, SecureZIP for z/OS automatically decrypts file names for anyone on a recipient list for the encrypted file names.
If file names are encrypted using a password (with or without a recipient list), SecureZIP for z/OS (and PKZIP for z/OS Enterprise Edition) requests a password when anyone who is not on the recipient list tries to open the archive. If the correct password is not entered, PKZIP/SecureZIP does not open the archive.
Security Examples
Below are examples of how to invoke SecureZIP for z/OS processing using ISPF panels and JCL along with sample output listings.
SecureZip using Recipients or Combo When protection modes of Recipient or Combo are selected, recipients can be designated such that a password is not required to extract the data.
If a password is entered, the lines will be concatenated to create a single password string of up to 250 characters and each line must begin and end with a non-blank.
Each recipient is represented by a public-key x.509 digital certificate. The public-key certificates can be stored and accessed in one or more of the following locations:
Individual data sets (or PDS members)
The Local certificate store Database as described by DB Profile
One or more network LDAP servers as described by LDAP Profile. (LDAP operations require SecureZIP for z/OS Enterprise Edition.)
Recipient designations:
LDAP:CN=Joe Smith
dsn://'PKZIP.CERTSTOR.PRIVATE(MAS2005)',R,password=abcdef
LDAP:mail=*@location.com
It is important to note the following:
79
CN=Joe Smith may return more than one recipient digital certificate. The LDAP entry for Joe Smith may contain multiple certificates. Certificates are frequently valid for only one year, so a recipient may have a certificate for each year with the company.
A local PDS has a certificate loaded into member MAS2005, which may represent a specific person's 2005 certificate. In this case, the R indicates that the certificate is required for processing to be performed. In addition, this certificate is a private-key certificate, so the export password is necessary for the public-key portion to be extracted from it.
db:EM= (or CN= for common name) may be used to locate a public-key certificate from within the local certificate store database. Private-key certificates may also be stored in the database, in which case the private-key password must also be coded to access it.
LDAP:mail=*@location.com demonstrates that masked requests may be made to an LDAP server. However, caution must be used not to make search criteria too broad, to avoid related high CPU and virtual storage requirements.
Zip Compress File(s) to an Archive FIle (Option ‘Z’ ) Using Recipients Below is the main ZIP compression panel. Here you place a “Y” in the Encryption option field to encrypt.
SecureZIP ZIP Processing Command ===> Archive File Information: File Name : 'FPD.SEQ.ZIP' File Type : 1 ( 1 = SEQ, 2 = PDS, 3 = VSAM, 4= PDSE) More Attributes : N ( Y - Yes, N - Take Defaults) Zip file information: File to compress : 'FPD.TEST.SEQ3' Zipped DSN : Encryption : Y ( Y - Encrypt files) : N ( Y - View typed password) Format : ( B -Binary T -Text D -Detect BV -Binary-Variable) More Files : N ( Y - Enter additional file names, N - None) Security options: Security required : N ( Y - To Display Security Options Dialog) Processing options: Simulation Mode : N ( Y - Test file selection, N - Normal Processing) Zip Function : A ( A - Add, F - Freshen, U - Update, D - Delete) Processing Mode : B ( F - Foreground, B - Batch) Batch JCL Status : C ( C - New Dataset, A - Add to existing Dataset) Advanced Options : N ( Y - Change Defaults, N - None) Enter VIEW on command line to VIEW archive
SecureZIP Encryption Using Individual Recipients as Input The next panel that appears when you have selected Encryption is a pop-up that allows you to select the method of encryption and either enter the password and the recipient, or the password alone, or the recipient alone, to be used to encrypt the file.
80
PKZZ005 SecureZIP ZIP Processing Command ===> More: Security options: Password protect : N ( Y - Use Passwords) : N ( Y - View typed pwd) Encryption: Algorithm : BSAFE_AES128 / for selection list Filename Encryption: N ( Y - Encrypt file names in the Archive) ------------------------------------------------------------------------- SecureZIP certificate-based operations. (Page down for all options) Certificate Encryption: Recipients : N ( Y - Digital Certificate Encryption) Validation Policy: Y Trusted Y Expired Y Revoked Signing: Archive : N ( Y - Sign Archive Central Directory) Files : N ( Y - Sign Files) Hash Algorithm : SHA-1 (MD5, SHA-1) Validation Policy: Y Trusted Y Expired Y Revoked SecureZIP certificate-based operations. (Page down for all options) Certificate Encryption: Recipients : Y ( Y - Digital Certificate Encryption) Validation Policy: Y Trusted Y Expired Y Revoked Signing: Archive : N ( Y - Sign Archive Central Directory) Files : N ( Y - Sign Files) Hash Algorithm : SHA-1 (MD5, SHA-1) Validation Policy: Y Trusted Y Expired Y Revoked Authentication: Archive : N ( Y - Authenticate Archive Directory) Validation Policy: Y Trusted Y Expired Y Revoked Y Tampercheck ------------------------------------------------------------------------- Reporting: Certificate Report : Y ( Y - Verbose certificate selection info)
In this example we are going to enter “RECIPIENTS=Y” to allow the use of certificate processing. This displays pop-up screen PKSZ001 so that intended recipients can be identified (see screen below).
Notice that the Certificate Report option has a “Y”. This places a VERBOSE control card in the input stream to generate additional details on the locations searched for certificate information and the status of the search. A set of ZPCM024C messages display in the SecureZIP program output to show how each RECIPIENT request was resolved.
SecureZIP Encryption OPTION ===> More: Selection Mode: Recipients / to Edit the profile used to satisfy DB: and LDAP: requests DB Profile > 'SECZIP.FPD.PROFILES(DB810X)' LDAP Profile> 'SECZIP.FPD.JCL(LDAPFPD1)' / Edit a file containing a set of -RECIPIENT commands. S Search the Local Certificate Store to build a list M Data set member selection list Recipient List: 'SECZIP.FPD.CERTSTOR.PROFILES($RECIPS)'
81
Individual Recipients: A -RECIPIENT() request will be built for each of of the following requests. 1. 2. 3. 4. 5. Note: Recipient requests are cumulative. All requests from the Recipient List, Individual Recipients, the configured default RECIPIENT and MASTER RECIPIENT will be included.
The DB Profile member contains the definitions for the local certificate store that were created by the SecureZIP administrator. The Recipient List member $RECIPS identifies a file from which RECIPIENT commands can be included. In addition, a specific recipient with a common name of “PKWARE Test3” is identified.
SecureZIP Certificate Report Option
----------------------------------------------------------- Digital Certificate Request List Req'd Private Recip-ient //'PKZIP.CERTSTOR.PRIVATE(MAS2005)' FILE FOUND *REQUIRED* Cond'l Public Recipient CN=Joe Smith FILE NOT_FOUND ------------------------------------------------------------
SecureZIP Verification Window Below is a pop up window to allow you to verify your selected security options.
Command ===> The following security options have been selected: Recipient-based BSAFE_AES256 Encryption No Filename Encryption No Archive Directory Signature No File Signatures No Authentication of Archive Signature Press ENTER to continue with detailed specifications of each, or PF3 or 'END' to respecify the basic security options.
SecureZIP Encryption Using Individual Recipients-Generated JCL Below is the generated JCL to submit to encrypt this archive. The JCL contains the recipients added in the Encryption panel above.
82
****** ********************************* Top of Data ************************** 000001 //FPDCS1 JOB 'ACCOUNTING INFO',CLASS=A,REGION=8M, 000002 // MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID 000003 //* 000004 //ZIPIT EXEC PGM=PKZIP 000005 //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD 000006 //SYSPRINT DD SYSOUT=* 000007 //SYSIN DD * 000008 * PANEL INPUT COMMANDS: 000009 -ENCRYPTION_METHOD(BSAFE_AES128) 000010 * Configured Profile: 000011 -INCLUDE_CMD(PKWARE.MVS.JCL(DBPROF)) 000012 -INCLUDE_CMD(MAS.TEST.CERTSTOR.PROFILES($RECIPS)) 000013 -RECIPIENT(db:cn=Joe Smith) 000014 -RECIPIENT(db:cn=PKWARE Test3) 000015 -VERBOSE 000016 -ARCHIVE_DSN(FPD.SEQ.ZIP) 000017 -ARCHIVE_DSORG(PS) 000018 -ACTION(ADD) 000019 FPD.TEST.SEQ3 000020 /*
SecureZIP Encryption Using Recipient Job Output Listing with VERBOSE Below is the output from the SecureZIP for z/OS batch job submitted. The output listing contains all pertinent information related to certificate processing. The additional certificate information is generated as a result of using the VERBOSE control card.
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 -INCLUDE_CMD=PKZIP.IVP.JCL(DEVCERT1) -ECHO=N * PANEL INPUT COMMANDS: -ENCRYPTION_METHOD(BSAFE_AES128) * Configured Profile: -INCLUDE_CMD(PKWARE.MVS.JCL(DBPROF)) *---------------------------------------------------------------------* * PROFILE PKWARE.MVS.JCL(DBPROF) * *---------------------------------------------------------------------* * DATABASE ACCESS CONTROL CARDS -{CSPUB=4;1;SECZIP.CERTSTOR.PUBLIC} -{CSPRVT=4;1;SECZIP.CERTSTOR.PRIVATE} -{CSPUB_DBX=SECZIP.CERTSTOR.DBX} -{CSPUB_DBX_PATH_CN=SECZIP.CERTSTOR.PATHCN} -{CSPUB_DBX_PATH_EM=SECZIP.CERTSTOR.PATHEM} -{CSPUB_DBX_PATH_PUBKEY=SECZIP.CERTSTOR.PATHPUBK} -INCLUDE_CMD(PKWARE.MVS.JCL(LDAPPROF)) *---------------------------------------------------------------------* * PROFILE PKWARE.MVS.JCL(LDAPPROF) * *---------------------------------------------------------------------* -{LDAP=1;LDAP1234.PKWARE.COM;4389;0;0;;;*CN;O=PKWARE} -RECIPIENT(db:cn=PKWARE TEST1) -RECIPIENT(db:cn=PKWARE Test2) -RECIPIENT(db:[email protected]) -VERBOSE -LOGGING_LEVEL(VERBOSE) -ARCHIVE_DSN(FPD.SEQ.ZIP) -ARCHIVE_DSORG(PS)
83
-ACTION(ADD) FPD.TEST.SEQ3 ZPCM011I Processing EXEC PARM parameters ZPCS200I Opening Common Name DB Index (//'SECZIP.CERTSTOR.PATHCN') ZPCS200I Opening Email Address DB Index (//'SECZIP.CERTSTOR.PATHEM') ZPCM023I Digital Certificate Store Configuration {CSCA=1;1;PKWARE.MVS.CERTSTOR.PUBLIC(CAP7)} {CSROOT=1;1;PKWARE.MVS.CERTSTOR.PUBLIC(ROOTP7)} {CSPUB=4;1;SECZIP.CERTSTOR.PUBLIC} {CSPRVT=4;1;SECZIP.CERTSTOR.PRIVATE} {CSPUB_DBX=SECZIP.CERTSTOR.DBX} {CSPUB_DBX_PATH_CN=SECZIP.CERTSTOR.PATHCN} {CSPUB_DBX_PATH_EM=SECZIP.CERTSTOR.PATHEM} {CSPUB_DBX_PATH_PUBKEY=SECZIP.CERTSTOR.PATHPUBK} ZPCM023C --------------------------------------- ZPCM024I Digital Certificate Request List ZPCM024C Cond'l Public Recipient //'SECZIP.CERTSTOR.PUBLIC(GEN50874)' ZPCM024C FILE FOUND ZPCM024C Cond'l Public Recipient //'SECZIP.CERTSTOR.PUBLIC(GEN51550)' ZPCM024C FILE FOUND ZPCM024C -------------------------------- ZPCM025I Digital Certificates Found: 2 ZPCM025C Joe Smith;[email protected]; ZPCM025C PKWARE Test3;[email protected]; ZPCM025C -------------------------------- ZPAP900I NO API REQUIRED ZPAM030I OUTPUT Archive opened: FPD.SEQ.ZIP ZPCM017I A total of 1 ADD/UPDATE candidate file(s) were identified. ZPCO100I Compression Task { 5} TCB: 008D1858 Started. ZPCM100I Configuration Manager Shutdown. Posting Main Task: 00000000 ZPAM253I ADDED File FPD.TEST.SEQ3 ZPAM254I as FPD/TEST/SEQ3 ZPAM255I (DEFLATED 79%/78%) SecureZIP(R): BSAFE_AES128 ORIG. SIZE 216,800; ZIP SIZE 47,608 ZPAM140I FILES: ADDED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPAM101I Archive Manager Task { 3} TCB: 008D1E88 shutdown begun. ZPAM109I Archive Manager Task { 3} TCB: 008D1E88 shutdown complete. ZPCO101I Compression Task { 5} TCB: 008D1858 shutdown begun. ZPCO109I Compression Task { 5} TCB: 008D1858 shutdown complete. ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
SecureZIP Encryption Using Recipient Job Output Listing Without VERBOSE Below is the output from the SecureZIP for z/OS batch job submitted. This output shows the result of not using VERBOSE control card.
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 -INCLUDE_CMD=PKZIP.IVP.JCL(DEVCERT1) -ECHO=N * PANEL INPUT COMMANDS: -ENCRYPTION_METHOD(BSAFE_AES128) * Configured Profile: -INCLUDE_CMD(PKWARE.MVS.JCL(DBPROF)) *---------------------------------------------------------------------* * PROFILE PKWARE.MVS.JCL(DBPROF) * *---------------------------------------------------------------------* * DATABASE ACCESS CONTROL CARDS
84
-{CSPUB=4;1;SECZIP.CERTSTOR.PUBLIC} -{CSPRVT=4;1;SECZIP.CERTSTOR.PRIVATE} -{CSPUB_DBX=SECZIP.CERTSTOR.DBX} -{CSPUB_DBX_PATH_CN=SECZIP.CERTSTOR.PATHCN} -{CSPUB_DBX_PATH_EM=SECZIP.CERTSTOR.PATHEM} -{CSPUB_DBX_PATH_PUBKEY=SECZIP.CERTSTOR.PATHPUBK} -INCLUDE_CMD(PKWARE.MVS.JCL(LDAPPROF)) *---------------------------------------------------------------------* * PROFILE PKWARE.MVS.JCL(LDAPPROF) * *---------------------------------------------------------------------* -{LDAP=1;LDAP1234.PKWARE.COM;4389;0;0;;;*CN;O=PKWARE} -RECIPIENT(db:cn=PKWARE TEST1) -RECIPIENT(db:cn=PKWARE Test2) -RECIPIENT(db:[email protected]) -ARCHIVE_DSN(FPD.SEQ.ZIP) -ARCHIVE_DSORG(PS) -ACTION(ADD) FPD.TEST.SEQ3 ZPAM030I OUTPUT Archive opened: FPD.SEQ.ZIP ZPAM253I ADDED File FPD.TEST.SEQ3 ZPAM254I as FPD/TEST/SEQ3 ZPAM255I (DEFLATED 79%/78%) SecureZIP(R): BSAFE_AES128 ORIG. SIZE 216,800; ZIP SIZE 47,608 ZPAM140I FILES: ADDED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
SecureZIP Encryption Using a Recipients List In the example below, we enter “RECIPIENTS” using a data set that contains the recipients. Placing a slash / in front of the data set name enables you to edit the list prior to execution.
SecureZIP ZIP Processing +-----------------------------------------------------------------------------+ ³ SecureZIP Encryption ³ ³ OPTION ===> ³ ³ More: ³ ³ ³ ³ ---------------------------------------------------------------------- ³ ³ Recipient Section (For Protection Modes "Recipient" or "Combo") ³ ³ ³ ³ / to Edit/View the profile ³ ³ DB Profile > 'PKWARE.MVS.JCL(DBPROF)' ³ ³ LDAP Profile> 'PKWARE.MVS.JCL(LDAPPROF)' ³ ³ ³ ³ / to Edit/View the list where -RECIPIENT requests are. ³ ³ Recipient List: 'PKWARE.MVS.JCL(RECIPL1)' ³ ³ ³ ³ Individual Recipients: A -RECIPIENT() request will be built with each value ³ ³ 1. ³ ³ 2. ³ ³ 3. ³ ³ 4. ³ ³ 5. ³ ³ ³ ³ ³ +-----------------------------------------------------------------------------+
Editing the Recipients List You can add, change, or delete any of your existing recipients.
85
File Edit Edit_Settings Menu Utilities Compilers Test Help -------------------------------------------------------------------------------- EDIT PKWARE.MVS.JCL(RECIPL1) - 01.01 Columns 00001 Command ===> Scroll === ****** ********************************* Top of Data *************************** 000001 *---------------------------------------------------------------------* 000002 * Recipient list 1 PKWARE.MVS.JCL(RECIPL1) * 000003 *---------------------------------------------------------------------* 000004 -RECIPIENT(db:cn=PKWARE TEST1) 000005 -RECIPIENT(db:cn=PKWARE Test2) 000006 -RECIPIENT(db:[email protected]) ****** ******************************** Bottom of Data *************************
SecureZIP Encryption Using a Recipients List Below is the generated JCL using the recipients list. Notice the control card INCLUDE_CMD(PKWARE.MVS.JCL(RECIPL1)). This brings into SecureZIP for z/OS your recipients.
File Edit Edit_Settings Menu Utilities Compilers Test Help -------------------------------------------------------------------------------- EDIT FPD.PKWARE.JCL Columns 00001 Command ===> Scroll === ****** ********************************* Top of Data *************************** 000001 //FPDCS1 JOB 'ACCOUNTING INFO',CLASS=A,REGION=8M, 000002 // MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID 000003 //* 000004 //ZIPIT EXEC PGM=PKZIP 000005 //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD 000006 //SYSPRINT DD SYSOUT=* 000007 //SYSIN DD * 000008 * PANEL INPUT COMMANDS: 000009 -ENCRYPTION_METHOD(BSAFE_AES128) 000010 * Configured Profile: 000011 -INCLUDE_CMD(PKWARE.MVS.JCL(DBPROF)) 000012 -INCLUDE_CMD(PKWARE.MVS.JCL(LDAPPROF)) 000013 -INCLUDE_CMD(PKWARE.MVS.JCL(RECIPL1)) 000014 -VERBOSE 000015 -ARCHIVE_DSN(FPD.SEQ.ZIP) 000016 -ARCHIVE_DSORG(PS) 000017 -ACTION(ADD) 000018 FPD.TEST.SEQ3 000019 /* ****** ******************************** Bottom of Data *************************
SecureZIP Halt Process Request If you press PF3 on the build screens, a popup dialog asks you if you wisk to halt the current process and begin again.
Command ===> Do you wish to cancel the ZIP run? Press ENTER to continue. Press PF3 or enter CANCEL command to return.
86
SecureZIP Encryption Using LDAP Search for Recipients Below we enter recipients using a search of the LDAP(s) that are configured in the LDAP profile. The search criteria in this instance is the common name (CN). The CN request is for a name fragment beginning with M*, F*, S*, and B*. This will generate recipients that match those criteria.
SecureZIP ZIP Processing +-----------------------------------------------------------------------------+ ³ SecureZIP Encryption ³ ³ OPTION ===> ³ ³ More: ³ ³ ³ ³ ---------------------------------------------------------------------- ³ ³ Recipient Section (For Protection Modes "Recipient" or "Combo") ³ ³ ³ ³ / to Edit/View the profile ³ ³ DB Profile > 'PKWARE.MVS.JCL(DBPROF)' ³ ³ LDAP Profile> 'PKWARE.MVS.JCL(LDAPPROF)' ³ ³ ³ ³ / to Edit/View the list where -RECIPIENT requests are. ³ ³ Recipient List: ³ ³ ³ ³ Individual Recipients: A -RECIPIENT() request will be built with each value ³ ³ 1. LDAP:CN=M* ³ ³ 2. LDAP:CN=F* ³ ³ 3. LDAP:CN=S* ³ ³ 4. LDAP:CN=B* ³ ³ 5. ³ ³ ³ ³ ³ +-----------------------------------------------------------------------------+
SecureZIP Encryption Using LDAP Search for Recipients-Generated JCL
EDIT FPD.PKWARE.JCL Columns 00001 Command ===> Scroll === ****** ********************************* Top of Data *************************** 000001 //FPDCS1 JOB 'ACCOUNTING INFO',CLASS=A,REGION=8M, 000002 // MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID 000003 //* 000004 //ZIPIT EXEC PGM=PKZIP 000005 //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD 000006 //SYSPRINT DD SYSOUT=* 000007 //SYSIN DD * 000008 * PANEL INPUT COMMANDS: 000009 -ENCRYPTION_METHOD(BSAFE_AES128) 000010 * Configured Profile: 000011 -INCLUDE_CMD(PKWARE.MVS.JCL(DBPROF)) 000012 -INCLUDE_CMD(PKWARE.MVS.JCL(LDAPPROF)) 000013 -RECIPIENT(LDAP:CN=M*) 000014 -RECIPIENT(LDAP:CN=F*) 000015 -RECIPIENT(LDAP:CN=S*) 000016 -RECIPIENT(LDAP:CN=B*) 000017 -VERBOSE 000018 -ARCHIVE_DSN(FPD.SEQ.ZIP) 000019 -ARCHIVE_DSORG(PS) 000020 -ACTION(ADD) 000021 FPD.TEST.SEQ3
87
SecureZIP Encryption Using LDAP Search for Recipients - Output
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 -INCLUDE_CMD=PKZIP.IVP.JCL(DEVCERT1) -ECHO=N * PANEL INPUT COMMANDS: -ENCRYPTION_METHOD(BSAFE_AES128) * Configured Profile: -INCLUDE_CMD(PKWARE.MVS.JCL(DBPROF)) *---------------------------------------------------------------------* * PROFILE PKWARE.MVS.JCL(DBPROF) * *---------------------------------------------------------------------* * DATABASE ACCESS CONTROL CARDS -{CSPUB=4;1;SECZIP.CERTSTOR.PUBLIC} -{CSPRVT=4;1;SECZIP.CERTSTOR.PRIVATE} -{CSPUB_DBX=SECZIP.CERTSTOR.DBX} -{CSPUB_DBX_PATH_CN=SECZIP.CERTSTOR.PATHCN} -{CSPUB_DBX_PATH_EM=SECZIP.CERTSTOR.PATHEM} -{CSPUB_DBX_PATH_PUBKEY=SECZIP.CERTSTOR.PATHPUBK} -INCLUDE_CMD(PKWARE.MVS.JCL(LDAPPROF)) *---------------------------------------------------------------------* * PROFILE PKWARE.MVS.JCL(LDAPPROF) * *---------------------------------------------------------------------* -{LDAP=1;LDAP1234.PKWARE.COM;4389;0;0;;;*CN;O=PKWARE} -RECIPIENT(LDAP:CN=M*) -RECIPIENT(LDAP:CN=F*) -RECIPIENT(LDAP:CN=S*) -RECIPIENT(LDAP:CN=B*) -VERBOSE -LOGGING_LEVEL(VERBOSE) -ARCHIVE_DSN(FPD.SEQ.ZIP) -ARCHIVE_DSORG(PS) -ACTION(ADD) FPD.TEST.SEQ3 ZPCM011I Processing EXEC PARM parameters ZPCM023I Digital Certificate Store Configuration {CSCA=1;1;PKWARE.MVS.CERTSTOR.PUBLIC(CAP7)} {CSROOT=1;1;PKWARE.MVS.CERTSTOR.PUBLIC(ROOTP7)} {CSPUB=4;1;SECZIP.CERTSTOR.PUBLIC} {CSPRVT=4;1;SECZIP.CERTSTOR.PRIVATE} {CSPUB_DBX=SECZIP.CERTSTOR.DBX} {CSPUB_DBX_PATH_CN=SECZIP.CERTSTOR.PATHCN} {CSPUB_DBX_PATH_EM=SECZIP.CERTSTOR.PATHEM} {CSPUB_DBX_PATH_PUBKEY=SECZIP.CERTSTOR.PATHPUBK} {LDAP=1;LDAP1234.PKWARE.COM;4389;0;0;;;*CN;O=PKWARE} ZPCM023C --------------------------------------- ZPCM024I Digital Certificate Request List ZPCM024C Cond'l Public Recipient CN=M* ZPCM024C LDAP FOUND ZPCM024C Cond'l Public Recipient CN=F* ZPCM024C LDAP FOUND ZPCM024C Cond'l Public Recipient CN=S* ZPCM024C LDAP FOUND ZPCM024C Cond'l Public Recipient CN=B* ZPCM024C LDAP FOUND ZPCM024C -------------------------------- ZPCM025I Digital Certificates Found: 6 ZPCM025C PKWARE Test2;[email protected]; ZPCM025C PKWARE Test2;[email protected]; ZPCM025C Tom Miller;[email protected]; ZPCM025C PKWARE TEST1;[email protected]; ZPCM025C Ben Smith;[email protected];
88
ZPCM025C John Smith;[email protected]; ZPCM025C -------------------------------- ZPAP900I NO API REQUIRED ZPAM030I OUTPUT Archive opened: FPD.SEQ.ZIP ZPCM017I A total of 1 ADD/UPDATE candidate file(s) were identified. ZPCM100I Configuration Manager Shutdown. Posting Main Task: 00000000 ZPCO100I Compression Task { 5} TCB: 008D1A70 Started. ZPAM253I ADDED File FPD.TEST.SEQ3 ZPAM254I as FPD/TEST/SEQ3 ZPAM255I (DEFLATED 78%/78%) SecureZIP(R): BSAFE_AES128 ORIG. SIZE 216,800; ZIP SIZE 48,094 ZPAM140I FILES: ADDED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPAM101I Archive Manager Task { 3} TCB: 008D1E88 shutdown begun. ZPAM109I Archive Manager Task { 3} TCB: 008D1E88 shutdown complete. ZPCO101I Compression Task { 5} TCB: 008D1A70 shutdown begun. ZPCO109I Compression Task { 5} TCB: 008D1A70 shutdown complete. ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Selecting Filename Encryption To encrypt file names when encrypting and adding files to an archive, use the FILENAME_ENCRYPTION command.
Panel Option “Z” - Selecting Filename Encryption This panel appears when you have selected Encryption on the Zip panel. To add filename encryption, place a “Y” in that selection field.
+-----------------------------------------------------------------------------+ | SecureZIP Encryption | | OPTION ===> | | More: | | Main Processing Options | | Protection Mode : RECIPIENTS Password, Recipients, Combo | | Encryption Method : BSAFE_AES128 / for selection list | | Filename Encryption: Y Y/N | | Certificate Report : Y Y/N (Recipients shown in SYSPRINT) | | | | Password Section (For Protection Modes "Password" or "Combo") | | | | Enter Password below (up to 250 characters) | | ....5...10....5...20....5...30....5...40....5...50....5...60....5...70 | | | | | | | | Re-enter Password to verify: | | | | | | | | ---------------------------------------------------------------------- | | Recipient Section (For Protection Modes "Recipient" or "Combo") |
Zip Compress File(s) to an Archive FIle (Option ‘Z’ ) Using Passwords Below is the main ZIP compression panel. Here you place a “Y” in the Security required field.
89
SecureZIP ZIP Processing Command ===> Archive File Information: File Name : 'MAS1.TEMP.ZIP' File Type : 1 ( 1 = SEQ, 2 = PDS, 3 = VSAM, 4= PDSE) More Attributes : N ( Y - Yes, N - Take Defaults) Zip file information: File to compress : 'MAS.TEST.SEQ' Zipped DSN : Format : ( B -Binary T -Text D -Detect BV -Binary-Variable) More Files : N ( Y - Enter additional file names, N - None) Security options: Security required : Y ( Y - To Display Security Options Dialog) Processing options: Simulation Mode : N ( Y - Test file selection, N - Normal Processing) Zip Function : U ( A - Add, F - Freshen, U - Update, D - Delete) Processing Mode : B ( F - Foreground, B - Batch) Batch JCL Status : C ( C - New Dataset, A - Add to existing Dataset) Advanced Options : N ( Y - Change Defaults, N - None) Enter VIEW on command line to VIEW archive
SecureZIP Encryption The next panel that appears when you select Encryption is a pop-up that allows you to select the encryption algorithm and various security modes. To select password-based encryption, place a “Y” in the Password protect field. Press “Enter” and a pop-up menu appear to allow you to type in the password. You must enter the password twice to validate that you entered it correctly.
SecureZIP ZIP Processing Command ===> More: Security options: Password protect : Y ( Y - Use Passwords) : N ( Y - View typed pwd) Encryption: Algorithm : BSAFE_AES128 / for selection list Filename Encryption: N ( Y - Encrypt file names in the Archive)
90
SecureZIP Password Encryption Command ==> To encrypt file(s), enter a password and select an algorithm Data Set Name: MAS.TEST.SEQ Password (up to 250 characters): ....5...10....5...20....5...30....5...40....5...50....5...60....5...70 Re-enter password: Press ENTER to continue, PF3 to terminate processing.
Entering PF8 will display the additional information listed below.
Cryptographic Algorithms Placing a “/” in the Encryption Method field causes an additional panel to appear to allow you to select one of the Encryption Method options. Placing a “/” in the Select field next to the desired Encryption Method presents the panel below, which allows you to select an encryption method to use.
+----------------------------------------------------------------+ | SecureZIP Cryptographic Algorithm | | COMMAND ===> SCROLL ===> PAGE | | | | Enter a / by the desired Option Value and press ENTER | | | | Select Option Value | | ------ ------------------------------------------------------ | | BSAFE_AES128 | | BSAFE_AES192 | | BSAFE_AES256 | | BSAFE_DES | | BSAFE_3DES | | BSAFE_RC4 | | AES128 | | AES192 | | AES256 | | STANDARD | *********************** Bottom of data *********************** | +----------------------------------------------------------------+
When you press “Enter”, the original Zip panel reappears with the return code from SECZIP in the upper right hand corner.
91
SecureZIP for z/OS 9.0 Zip PKZIP Done: RC=0 Command ===> Archive File Information: File Name : 'FPD.TEST600.ZIP' File Type : 1 ( 1 = SEQ, 2 = PDS, 3 = VSAM, 4= PDSE) More Attributes : N ( Y - Yes, N - Take Defaults) Zip file information: File to compress : 'PKWARE.MVS.JCL' Zipped DSN : Encryption : Y ( Y - Encrypt files) : N ( Y - View typed password) Format : ( B -Binary T -Text D -Detect BV -Binary-Variable) More Files : N ( Y - Enter additional file names, N - None) Security options: Security required : Y ( Y - To Display Security Options Dialog) Processing options: Simulation Mode : N ( Y - Test file selection, N - Normal Processing) Zip Function : A ( A - Add, F - Freshen, U - Update, D - Delete) Processing Mode : F ( F - Foreground, B - Batch) Advanced Options : N ( Y - Change Defaults, N - None) Enter VIEW on command line to VIEW archive To EXIT Press PF3 or enter X For HELP Press PF1
If the “Batch” option is selected, the following JCL is generated for you to review and submit.
//JOBNAME JOB 'ACCOUNTING INFO',CLASS=A,REGION=8M, // MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID //ZIPIT EXEC PGM=PKZIP //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSIN DD * * PANEL INPUT COMMANDS: -PWD(| test) -ENCRYPTION_METHOD(BSAFE_AES128) -SIMULATE(Y) -ARCHIVE_DSN(FPD.TEST600.ZIP) -ARCHIVE_DSORG(PS) -ACTION(ADD) PKWARE.MVS.JCL /*
Following is an output listing of a batch job submitted. The message ZPAM255I displays the encryption method used.
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 *PANEL INPUT COMMANDS: -PASSWORD (**********) -ENCRYPTION_METHOD(BSAFE_AES128) -ARCHIVE_DSN(FPD.TEST600.ZIP) -ARCHIVE_DSORG(PS) -ACTION(ADD) PKWARE.MVS.JCL ZPAM030I OUTPUT Archive opened: FPD.TEST600.ZIP
92
ZPAM253I ADDED File PKWARE.MVS.JCL(ACZDFLT) ZPAM254I as PKZIP/FPD/JCL/ACZDFLT ZPAM255I (DEFLATED 73%/72%) SecureZIP(R) ENCRYPTION:BSAFE_AES128 ORIG. SIZE 4,080; ZIP SIZE 1,126 ZPAM253I ADDED File PKWARE.MVS.JCL(ACZDFLTB) ZPAM254I as PKZIP/FPD/JCL/ACZDFLTB ZPAM255I (DEFLATED 73%/72%) SecureZIP(R) ENCRYPTION:BSAFE_AES128 ORIG. SIZE 4,080; ZIP SIZE 1,126 ZPAM253I ADDED File PKWARE.MVS.JCL(AESASM) ZPAM140I FILES: ADDED EXCLUDED BYPASSED IN ERROR ZPAM140I 203 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
UNZip File(s) from an Archive (Option ‘U’ ) Using Recipients
To unzip a recipient-encrypted archive file requires no changes on the Extract panel.
Previously, we described the placement of the pointer to the private-key certificate, used for decryption, in the Runtime Configuration panel.
SecureZIP Runtime Configuration Option ===> Certificate Store Settings ( ENTER to validate PF7/PF8 to scroll) / to Edit the configuration file Private-Cert> ‘PKWARE.MVS.JCL(CERTPROF)' DB Profile > 'PKWARE.MVS.JCL(CCFGFPD1)' LDAP Profile> 'PKWARE.MVS.JCL(LDAPFPD1)' ------------------------------------------------------------------------------- ***** Top of Data ************************************************************** Private-key Certificate Recipient(s): ===================================== *---------------------------------------------------------------------* * Profile PKWARE.MVS.JCL(CERTPROF) * *---------------------------------------------------------------------* -recipient(db:cn=PKWARE TEST1,R,PASSWORD=xxxxxxxx)
Unzip Panel (Option ‘U’ ) Using Recipients SecureZIP for z/OS uses the Private-Cert pointer to find and use your private certificate to do the decryption.
SecureZIP Extract Processing Command ===> Enter Archive from which file(s) are to be extracted: Archive Name . . . : 'FPD.SEQ.ZIP' Enter Files to be extracted: File Selection . . : Rename to. . . . . : File Decryption. . : N ( Y - Enter password) : N ( Y - View typed password) More Files . . . . : N ( Y - Enter additional file names, N - None) Security options: Security required. : N ( Y - To Display Security Options Dialog) Enter processing options: Simulation Mode. . : N ( Y - Test file selection, N - Normal Processing)
93
Integrity Check. . : Y ( Y - Yes, N - No) Overwrite/Insert . : O ( O - Overwrite, I - Ins Mbr, OI - Both, N - None) Processing Mode. . : B ( F - Foreground, B - Batch) Batch JCL Status . : C ( C - New Dataset, A - Add to existing Dataset) Advanced Options . : N ( Y - Change Defaults, N - None) Preallocate file . : N ( Y - Prompt for allocation info, N -Use Defaults) File type : ( 1 - PDS, 2 - PS, 3 - VSAM, 4 - PDSE) Enter VIEW in the command field to VIEW an archive To EXIT Press PF3 Press ENTER to process For HELP Press PF1
Unzip Output Using Recipients Below is the output generated from the previous Unzip request.
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 -INCLUDE_CMD=PKZIP.IVP.JCL(DEVCERT1) -ECHO=N * Configured Profile: -INCLUDE_CMD(PKWARE.MVS.JCL(DBPROF)) *---------------------------------------------------------------------* * PROFILE PKWARE.MVS.JCL(DBPROF) * *---------------------------------------------------------------------* * DATABASE ACCESS CONTROL CARDS -{CSPUB=4;1;SECZIP.CERTSTOR.PUBLIC} -{CSPRVT=4;1;SECZIP.CERTSTOR.PRIVATE} -{CSPUB_DBX=SECZIP.CERTSTOR.DBX} -{CSPUB_DBX_PATH_CN=SECZIP.CERTSTOR.PATHCN} -{CSPUB_DBX_PATH_EM=SECZIP.CERTSTOR.PATHEM} -{CSPUB_DBX_PATH_PUBKEY=SECZIP.CERTSTOR.PATHPUBK} * Configured Private-Key Recipients: -INCLUDE_CMD(PKWARE.MVS.JCL(CERTPROF)) *---------------------------------------------------------------------* * Profile PKWARE.MVS.JCL(certprof) * *---------------------------------------------------------------------* -recipient(db:cn=PKWARE TEST1,R,PASSWORD=******) *-recipient(dsn://'PKZIP.IVP.CERT.ADMIN04.PFX',password=password) * Panel Commands: -ACTION(TEST) -SUPPRESS_DYNALLOC_MSGS -TRACE_DYNALLOC(0) -ARCHIVE_DSN(FPD.SEQ.ZIP) -OUTFILE_OVERWRITE(Y) ZPAM030I INPUT Archive opened: FPD.SEQ.ZIP ZPEX001I tested okay FPD/TEST/SEQ3 ZPAM140I FILES: TESTED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
View Display the Contents of an Archive File (Option ‘V’ )
When a file has been encrypted, one of the following indicators describing the strength of encryption is displayed before the file name.
+ Password-only "Standard" (96-bit) encryption.
94
! Password-only (128-bit or above) encryption.
$ Recipient-only Digital Certificate encryption.
& Combination Password/Recipient encryption.
SecureZIP View Archive Command ===> Enter name of archive to be viewed: Archive Name : 'FPD.TEST.AUTH.ZIP' Filename Filter : Security options: Security required : N ( Y - To Display Security Options Dialogue) Enter VIEW Options: View Type . .: V ( V - View, D - Detail, B - Brief, S - Scan Sort Output : N ( Y - Yes, N - No) Sort Field . : ( D - Date, N - Name, O - Offset, P - Percent, S - Size) Sort Order . : ( A - Ascending, D - Descending) Processing Mode. : F ( F - Foreground, B - Batch) Batch JCL Status : C ( C - New Dataset, A - Add to existing Dataset) Additional Commands: To EXIT Press PF3 For HELP Press PF1
SecureZIP View Archive Row 1 to 1 of 1 Command ===> SCROLL ===> PAGE Name of Archive : 'FPD.SEQ.ZIP' Primary commands: LOCATE to position list or SORT to sort list. Enter line command or '/' for list of valid line commands. Press PF1 for HELP. Cmd File Name Zipped Zipped Unzipped Comp Type Volume(s) Message Date/Time Size Size Ratio ---------------- ------ ------ ----- ---- ------- $ FPD/TEST/SEQ3 5/25/2005 11:16 47608 222.2K 78% TEXT FPD002
View Detail Display The View Detail option of the View panel describes the encryption algorithm used to encrypt, along with certificate information.
*********************************************************** Top of Data *** ZPGE001T UNZIP STARTUP STORAGE QUERY: 24BIT= 5172K 31BIT= 28840K C ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright 1989-2006 PKWARE Inc. All rights reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=2066 Processor Group=00 Serial Number= ZPLI001I OS Level: HBB7707 SP7.0.4 -INCLUDE_CMD=PKZIP.IVP.JCL(DEVCERT1) -ECHO=N -CALLMODE(ISPF)
95
-ARCHIVE_DSN(FPD.SEQ.ZIP) -SUPPRESS_DYNALLOC_MSGS -TRACE_DYNALLOC(0) -ACTION(VIEWDETAIL) -CALLMODE(ISPF) -TRACEDALC0 -TRACE_DYNALLOC(0) ZPAM030I INPUT Archive opened: FPD.SEQ.ZIP ZPAM014I 1 file(s) are in the input Archive. ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE ZPAM013I ****************************************************************** ZPAM001I Filename: FPD/TEST/SEQ3 ZPAM002I File type: TEXT ZPAM003I Date/Time: 25-MAY-2005 12:00:00 ZPAM004I Compression Method: Deflate- Super Fast ZPAM005I Compressed Size: 47,608 ZPAM006I Uncompressed Size: 222,221 ZPAM007I 32-bit CRC: 213E63AC LHDR Offset: 0 ZPAM008I Created by: PK zSeries 9.0 ZPAM009I Needed to extract: ZipSpec 6.1 ZPAM010I Encryption: AES_128 Certificate Key BSAFE(R) ZPAM301I File Type: NONVSAM SEQUENTIAL ZPAM303I File Record Format: FB ZPAM304I File Allocation Type: BLK ZPAM305I File Primary Space Allocated: 48 ZPAM306I File Secondary Space Allocated: 10 ZPAM307I File Record Size: 80 ZPAM308I File Block Size: 6160 ZPAM309I File Volume(s) Used: FPD002 ZPAM310I File Creation Date: 2005/04/21 ZPAM311I File Referenced Date: 2005/05/25 ZPAM319I SMS Storage Class: PRIVATE ZPAM320I 3 recipient(s) were designated: ZPAM321I Recipient: PKWARE TEST1 ZPAM310I File Creation Date: 2005/04/21 ZPAM311I File Referenced Date: 2005/05/25 ZPAM319I SMS Storage Class: PRIVATE ZPAM320I 3 recipient(s) were designated: ZPAM321I Recipient: PKWARE TEST1 ZPAM322I Public Key Hash: 5D9E8B89B5948E9E853338A7250D64C5BED5E9E7 ZPAM323I Email: [email protected] ZPAM324I Cert: //'PKWARE.MVS.CERTSTOR.PUBLIC(PK12003)' ZPAM321I Recipient: PKWARE Test2 ZPAM322I Public Key Hash: 07E091CE30862B61663CF9D356863BF84D3DC8D5 ZPAM323I Email: [email protected] ZPAM324I Cert: //'PKWARE.MVS.CERTSTOR.PUBLIC(PKT2005)' ZPAM013I ********************************************************************* ZPAM140I FILES: VIEWED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec) ********************************************************** Bottom of Data ****
Incorrect Password Use
The following four illustrations show what to expect if you enter an incorrect password. The third panel is a foreground execution of SECUNZIP. The upper right-hand corner contains the “Incorrect Password” message when the extraction fails. The fourth panel contains the output listing of a batch job with the message that the encrypted file has been skipped because of a missing or incorrect password.
96
Figure 1. Select the file to browse
SecureZIP View Archive Row 1 to 7 of 203 Command ===> SCROLL ===> PAGE Name of Archive : 'FPD.TEST600.ZIP' Primary commands: LOCATE to position list or SORT to sort list. Enter line command or '/' for list of valid line commands. Press PF1 for HELP. Cmd File Name Zipped Zipped Unzipped Comp Type Volume(s) Message Date/Time Size Size Ratio ---------------- ------ ------ ----- ---- ------- b ! PKZIP/FPD/JCL/ACZDFLT 2/11/2006 14:08 1126 4183 73% TEXT FPD002 ! PKZIP/FPD/JCL/ACZDFLTB 2/11/2006 14:08 1126 4183 73% TEXT FPD002 ! PKZIP/FPD/JCL/AESASM 2/11/2006 14:08 1110 3281 66% TEXT FPD002 ! PKZIP/FPD/JCL/AESASM2 2/11/2006 14:08 1110 3281 66% TEXT FPD002 ! PKZIP/FPD/JCL/APIMJB1 2/11/2006 14:08 502 1477 66% TEXT FPD002 ! PKZIP/FPD/JCL/ASMACTM 2/11/2006 14:08 374 903 58% TEXT FPD002 ! PKZIP/FPD/JCL/ASMACTRT
Figure 2. Enter the password
SecureZIP View Archive Row 1 to 7 of 203 EsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssN e SecureZIP for z/OS Encrypted File Password e e Command ==> e e e e File is encrypted. Enter password. e e e e Data Set Name: e e PKZIP/FPD/JCL/ACZDFLT e e e e Password (up to 250 characters): e e ....5...10....5...20....5...30....5...40....5...50....5...60....5...70 e e e e e e e e Re-enter password: e e e e e e e e Press ENTER to continue. e e Press PF3 to terminate processing e e e e e DsssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssM
97
Figure 3. Receive the error message and condition code if execution is in the Foreground.
SecureZIP for z/OS 9.0 View Arch Incorrect Password Command ===> SCROLL ===> PAGE Name of Archive : 'FPD.TEST600.ZIP' Primary commands: LOCATE to position list or SORT to sort list. Enter line command or '/' for list of valid line commands. Press PF1 for HELP. Cmd File Name Zipped Zipped Unzipped Comp Type Volume(s) Message Date/Time Size Size Ratio ---------------- ------ ------ ----- ---- ------- ! PKZIP/FPD/JCL/AESASM2 Brw 4 2/11/2006 14:08 1110 3281 66% TEXT FPD002 ! PKZIP/FPD/JCL/APIMJB1 2/11/2006 14:08 502 1477 66% TEXT FPD002 ! PKZIP/FPD/JCL/ASMACTM 2/11/2006 14:08 374 903 58% TEXT FPD002 ! PKZIP/FPD/JCL/ASMACTRT 2/11/2006 14:08 486 1067 54% TEXT FPD002 ! PKZIP/FPD/JCL/ASMALL 2/11/2006 14:08 5446 33867 83% TEXT FPD002 ! PKZIP/FPD/JCL/ASMAMGR 2/11/2006 14:08 438 1477 70% TEXT FPD002 ! PKZIP/FPD/JCL/ASMAPI
Figure 4. Receive the error message ZPEX014W Encrypted file skipped. Password not provided or not valid in the batch job output listing.
ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 * PANEL COMMANDS: -SIMULATE(Y) -PASSWORD(**********) -SUPPRESS_DYNALLOC_MSGS -TRACE_DYNALLOC(0) -ARCHIVE_DSN(FPD.TEST600.ZIP) -OUTFILE_OVERWRITE(Y) -UNZIPPED_DSN(**,FPDTST2) PKZIP/FPD/JCL/AESASM2 -CALLMODE(ISPF) ZPCM000I Simulation Mode has been selected for action EXTRACT ZPAM030I INPUT Archive opened: FPD.TEST600.ZIP ZPEX014W Encrypted file skipped. Password not provided or not valid. ZPEX002I ........................................................................ ZPEX003I Extracted to FPDTST2(AESASM2) ZPAM140I FILES: EXTRACTED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec) ************************************ Bottom of Data **********************************
98
7 File Selection and Name Processing
ZIP Processing File Selection
This chapter describes how to select files for ZIP processing. The chapter discusses the primary commands used, with notes and restrictions.
ZIP file directory entries in a ZIP archive are defined in a system-independent format that is compatible with UNIX systems and has been translated into the ASCII character set. Data set level separators are typically the forward slash (“/”), not the period (“.”) as in MVS (although the separator character can be specified through command actions).
Primary File Selection Inputs
Files that are candidates ZIP processing are selected when input parameters are processed and the old archive directory (if any) is read. Consequently, data set selection is controlled by three input sources:
Selection Source Effective ACTION Processes
Cataloged Dataset name command requests. ADD, UPDATE
INFILE command (JCL DD) requests. ADD, UPDATE
Input ZIP archive files. UPDATE, FRESHEN
Data set names found with the inputs listed above are combined into a single list of candidate files to be processed in the compression phase. A data set is selected only once. The following sections describe file selection from each of the input sources.
Cataloged Dataset Name Filter Requests
Requesting a file (or set of files) for ZIP processing by data set name triggers a standard search of the system catalog structure to determine eligible file names. Both NONVSAM and VSAM CLUSTER entries are used to identify candidates.
99
With data set name masking, multiple data set names may be identified from the system catalog.
Also see: RECURSE_LEVELS and VSAM.
Exclusion Filters
When requesting data sets for ZIP processing through the catalog, it may be desirable to filter out categories of files. In addition to the data set name masking characters (?, *, and **), PKZIPz provides the following commands to limit cataloged file selections:
Command Description
EXCLUDE(dsname|mask) Used to avoid selecting data sets based on the file name. Multiple EXCLUDE commands may be specified for an individual ZIP call.
SELECT_DSN_ALIAS(N) Used to avoid selecting data sets based on a catalog ALIAS definition.
SELECT_TAPE(N) Used to avoid processing tape files.
SELECT_VSAM(N) Used to avoid processing VSAM Clusters (this does not affect the archive data set organization). The archive may be VSAM, while the clusters are excluded for ZIP processing.
SELECT_MIGRATED(N) Used to avoid processing DISK files that have been migrated using a product such as IBM’s DFSMShsm. Files in this category are identified in the catalog as having a volume serial of “MIGRAT”.
SELECT_GDGALL Select all generations of a generation data group, while SELECT_NOGDGALL disables this feature (these are synonyms for the GDGALL_SUPPORT(Y|N) command).
RECURSE_LEVELS(N) Specifies if lower level data set name masking is not desired.
INFILE DD Requests
When requesting a data set for inclusion in ZIP processing with INFILE (with an associated JCL DD statement), operating system allocation is performed before PKZIPz execution begins.
JES2 SYSIN INFILE Support
JES2 SPOOLed input data is supported for input ZIP processing. By referencing a “//… DD * “statement with an INFILE command, the input stream is treated as a sequential file with DCB attributes of RECFM=FB, LRECL=80, and BLKSIZE=80. The filename generated is based on the DSN generated by the JES2 subsystem and is modified to end in “SYSIN”; for example, userid/jobname/JOBxxxxx/sysinfo/SYSIN. When performing a SECZIP operation against an existing archive, the DCB attributes (LRECL, BLKSIZE) are retained in the new archive unless explicitly overridden with new command values.
100
Note: When performing an EXTRACT of such a file, OUTFILE_… space allocation and volume information must be provided through the defaults module or command input stream since JES2 DD statements do not carry space attributes.
Input ZIP Archive Files
During an ACTION(FRESHEN) or ACTION(UPDATE) request, files contained within the old ZIP archive are added to the candidate list. Names as previously stored are used to search the system catalog for viability (any file names not found in the system catalog remain in the ZIP archive).
During an ACTION(COPY), only files within the input archive are candidates for copying to the new archive (which must be unique from the input archive).
File Selection Processing Notes
Files are not normally opened during the file selection phase of processing in order to streamline performance. However, some file characteristics are gathered for non-tape files at this time. PDS and PDSE data sets are opened so that their directory information can be reviewed and members identified for selection.
&SYSUID may be used in cataloged data set selection requests. Multiple components of PKZIPz are used to process File Selection requests. Various informational messages can be obtained from these internal components by turning on various logging and trace elements in the command stream. PDS member name selection can be requested through INFILE command parameters, associated JCL DD member reference, or Data set name parameters.
When an INFILE JCL DD specification is used and a member-name is coded in the JCL, it overrides any INFILE command parameters. (Only the member requested in the JCL are added to the selection list).
Dataset name command requests that also contain member request masks act in a cumulative fashion. All members from a PDS matching the requested masks are added to the candidate member list.
When both INFILE and Dataset Name command requests are made with member names, the multiple requests are merged into a cumulative list, and only one copy of the member is processed.
Because member name selections can also be placed on Dataset name masked requests, such as, more than one dataset is identified via a masked name, combinations of requests may result in different member-selection criteria for different datasets.
Member selection requests are compiled into an internal table, which is later used to match against the list of members available from the PDS. PDS members are selected in alphanumeric order.
101
Cataloged Dataset Name and INFILE Request Restrictions
Cataloged data set command requests must begin with a fully qualified first level. For example, SYS1.** is valid, but SYS*.** is not.
Cataloged data set name requests depend on the accuracy of the system catalog structure under which PKZIPz is executing. If a data set is cataloged, but does not exist on the cataloged device, an allocation error will occur later in processing.
INFILE(ddname) requests must accurately reflect the device and volume for the requested data set. “ddname” must be a fully-qualified DDname allocated to the job step (or TSO session).
INFILE requests, which refer to a DD statement that is a concatenated set of data sets, should have all files of the same DSORG and RECFM in accordance with OS/390 rules for concatenated data sets. The associated DD statement are opened with the DCB characteristics of the first file in the concatenation, and that file’s name represents the group for processing in the ZIP archive.
Data set ALIAS names may be used to identify candidate data sets. However, the system catalog structure is used to translate the ALIAS name to the true data set name for processing. When a data set name request is made, a message is issued to the output log indicating that an ALIAS to Truename translation has occurred. However, when an ALIAS name is used with an INFILE request, the operating system resolves the ALIAS entry to its associated Truename before program execution begins, and file selection only refers to the Truename as presented by OS/390.
Generation data sets (GDG) can be requested with a fully-qualified generation name, for example, “SYS1.BACKUP.G0020V00”; a relative generation level, for example, “SYS1.BACKUP(-1)”; or a GDG-base request. In all cases, identified candidates resolve to their fully qualified NONVSAM data set name, and each is processed as an independent entry.
GDG-base selection only applies to ZIP processing at the time of the request in accordance to the current catalog structure.
Relative generation selection is valid only with INFILE and JCL specifications.
UNZIP processing requires selection according to fully qualified generation names.
When GDG-base names are used via data set name command requests, each current ASSOCIATION entry in the catalog will be used to identify individual NONVSAM entries, and each is processed as an independent entry. This differs from the way GDG-base names are handled when INFILE is used.
When an INFILE request is used in conjunction with a DD statement to reference a GDG-base, standard MVS expansion of the GDGALL name occurs. This results in all generations being treated as a concatenation group, with the latest generation name being assigned to the file. You must take care in handling the resultant ZIP file, since the data from one or more generations are included in the file. This differs from the way GDG-base names are handled when data set name requests are made.
VSAM files are supported at the CLUSTER level only. Individual DATA and INDEX COMPONENT names should not be requested.
102
ZIP File Names
The ZIP archive architecture describes files in an internal format that is comparable to the UNIX file naming standards. Each file is described within a ZIP archive central directory entry and is represented in ASCII. The format carries an inherent directory/sub-directory format (with “/” as the directory separator character).
MVS data set names are converted to the standard ZIP archive file directory format before they are stored. For example, the data set “SYS1.PARMLIB(CLOCK00)” will appear in a ZIP archive as “SYS1/PARMLIB/CLOCK00”. A browse of the file in HEX format shows the ASCII representation for the characters, not EBCDIC.
The following commands are used to control the file names being saved and restored during ZIP and UNZIP processing: (See the appropriate command section later in this manual for more detail).
Summary of Commands Affecting ZIP Filename
Process Command Description
ZIP & UNZIP TRANSLATE_TABLE_FILEINFO EBCDIC <=> ASCII translate table
ZIP & UNZIP ZIPPED_DSN_SEPARATOR Default is “/” and replaces “.” In MVS DSNs, as well as separating a member name.
UNZIP UNZIPPED_DSN Allows the transformation of the internal ZIP Filename to an MVS standard name and allows the replacement of qualifiers during the process.
ZIP ZIPPED_DSN Allows the transformation of the MVS DSN to an internal ZIP Filename.
ZIP PATH Specifies whether the higher-level qualifiers should be stored as a directory pathname in the ZIP Filename.
UNZIP HIERARCHY Determines what should be done with the hi-level qualifiers (directory path structure) of the ZIP Filename during the conversion process.
UNZIP FILE_EXTENSION Specifies what should be done with a low-level extension (such as .TXT) during an EXTRACT request.
ZIP & UNZIP SIMULATE(Y) Provides a means of running a simulation to determine what the resulting names will be.
103
Essentials for running PKZIP/SECZIP and PKUNZIP/SECUNZIP
PKZIP/SECZIP can perform various actions for the following commands:
[ADD | COPY | DELETE | FRESHEN | UPDATE | VIEW ]
The actions are described below. ADD is the default action if no action is specified.
Command Description
ADD Adds files that are not already present into a new or existing ZIP archive.
COPY Copies a subset of an archive to a new archive.
DELETE Deletes selected files from an existing ZIP archive.
FRESHEN Updates existing files in an existing ZIP archive.
UPDATE Adds new files to or update existing files in an existing ZIP archive.
VIEW Displays details of selected files in an existing ZIP archive.
Each of the actions requires a ZIP archive to process, so the ARCHIVE command (or ARCHIVE_OUTDD) must always be specified.
–ARCHIVE(<ZIP dataset name>)
–ARCHIVE_DSNAME (<ZIP dataset name>)
Finally, you must specify the data set(s) to be added, copied, deleted, freshened, updated, or viewed in the archive. You can do this using standard MVS data set naming. For example:
MY.INPUT.DATA.SEQ
This line identifies a single file that is to be processed by PKZIP/SECZIP.
PKUNZIP/SECUNZIP For UNZIP to extract compressed data sets from a ZIP archive, PKUNZIP/SECUNZIP must be told three things:
The action to perform.
The archive from which the data sets are to be decompressed.
The files that are to be extracted from the archive.
PKUNZIP/SECUNZIP can perform the following commands:
[ EXTRACT | TEST | VIEW ]
The comands are described below. EXTRACT is the default if no command is specified.
104
Command Description
EXTRACT Extracts selected files from an existing ZIP archive.
TEST Deletes selected files from an existing ZIP archive.
VIEW Displays details of selected files in an existing ZIP archive.
Each of the commands requires a ZIP archive to process, so the ARCHIVE command (or alternative) must always be specified.
-ARCHIVE(<ZIP dataset name>)
-ARCHIVE_DSNAME (<ZIP dataset name>)
Finally, if a subset of all files in the archive is to be processed, you must specify the data set(s) to be extracted, tested, or viewed. You can do this using standard MVS data set naming (See note below) or internal ZIP file naming conventions. For example:
MY.INPUT.DATA.SEQ
MY/INPUT/DATA/SEQ
The default is to select all files from the archive.
Note: To process an MVS DSN format for SECUNZIP selection, the name must readily match the internal zip name with the exception of the directory separators, such as, substitutes for “/”, and the target MVS name must be acceptable to the operating system. (See OUTFILE_DD and UNZIPPED_DSN).
105
8 ZIP Files
Data Formats - Text or Binary
Data files are held within a ZIP archive in either text or binary format. Both formats are supported by ZIP-compatible products on other platforms; however, some restrictions apply to cross-platform use of the data. For example, workstation-based applications may not be able to process EBCDIC-based data that is commonly produced by S390 platforms.
Text data is represented by one of two character sets, EBCDIC or ASCII, in which individual alphanumeric characters are assigned an internal numeric code within the range of 0-255 (hexadecimal 00-FF). Although most of the same characters—for example, A-Z, a-z, 0-9—are contained in the EBCDIC and ASCII character sets, different code assignments are used for each. To preserve cross-platform compatibility of files containing only text characters, the DATA_TYPE(TEXT) or DATA_TYPE(DETECT) commands should be used. These commands direct PKZIPz to translate EBCDIC characters into the ASCII character set (the standard set used by ZIP-compatible products).
The DATA_TYPE(BINARY) command causes EBCDIC to ASCII character translation to be bypassed. This feature is useful when the file contains non-text data. (Warning: Binary fields may generate what appear to be record-delimited characters. Therefore, TEXT should not be used if binary data is present.) Note that a custom TRANSLATETABLE_DATA table can be built to substitute blanks for control characters (X’0D’ + ‘25’ EBCDIC or graphics or internal numeric representations; for example, packed, or binary numeric data), or if text-based data is to be extracted only to other EBCDIC based platforms.
All data within a file is treated the same during ZIP processing in accordance with the DATA_TYPE(TEXT) and DATA_TYPE(BINARY) commands. Care should be taken when zipping files that do not contain both text and binary data. Use of the DATA_TYPE(TEXT) command when binary data exists within the file will produce unpredictable results for fields containing binary data.
DATA_TYPE(BINARY) should be used to preserve data integrity; however, with this command, text data will not be translated into the ASCII format by UNZIP processing in a cross-platform environment.
As an advanced feature, DATA_TYPE(DETECT) is provided to instruct PKZIPz to read a portion of data from the input file (in accordance with the DATATYPE_DETECT_DEPTH value) and scan
106
it for non-translatable text characters using the active text translation table. If the number of translatable text characters (as specified by the DATATYPE_DETECT_TABLE) meets or exceeds the percentage specified by DATATYPE_TEXT_PERCENT, the file is treated as DATA_TYPE(TEXT). Otherwise, it is treated as if DATA_TYPE(BINARY) was used. In an exception to this rule, X’00’, or the NULL terminator character, which is commonly used in C language is allowed within the files. If it is unknown whether a file in the ZIP archive is text or binary, you may use the ACTION(VIEWDETAIL) command to examine the file attributes.
It is possible for members of the same PDS or PDSE to be treated differently when DATA_TYPE(DETECT) is used because of a varying mix of data. Each member is treated as an independent file during ZIP processing.
The command DATA_TYPE(DETECTX) is provided as an advanced feature to assist in identifying and translating text-based files for UNZIP processing. This is useful when the originating ZIP platform (typically a workstation) does not set the “text” indicator for the file in the archive.
Data Format - Text Records
In the context of ZIP archives, a “text file” is one that is stored in the ASCII format. A text file contains records of data, each separated by a delimiter to signify the end of the record.
Note: An EBCDIC file containing text information (such as source code) can be stored in its original format by using DATA_TYPE(BINARY), but it is not considered to be a “text” file within the ZIP architecture.
PKZIPz uses the default delimiter CR-LF (x'0D0A') at the end of each text record. You may choose to use a different delimiter by using the DATA_DELIMITER command (or other characters as specified in the command set). At the end of each ZIP’d file is a file terminator. The default file terminator for PKZIPz is Ctrl+Z (x'1A'). This file terminator can be changed by using the FILE_TERMINATOR command.
Note: The last record will have the data delimiter followed by the file terminator.
If you want the ZIPPED file to contain no data delimiters, you may specify CRLF(N) or DATA_DELIMITER(). If CR-LF is specified on ZIP, but CRLF(N) is specified on UNZIP, then PKZIPz treats any x'0D0A' as data characters, translates them into the EBCDIC equivalent, and embeds them in the output file. Although it is possible to align fixed-length records in an output file without CR-LF (by using input and output files with identical record lengths), care must be taken when using CRLF(N) because DATA_DELIMITER is the only explicit mechanism available to determine record lengths for text files.
At the time of UNZIP file extraction, PKZIPz changes text data from ASCII to EBCDIC by using a translation table. During installation, several translation tables are available, and the customizing process selects one as the default. Additional translation tables may be created through the customizing procedure.
Note that, during UNZIP processing, if the defined CR-LF character sequence (for example, x'0D0A') is not found in the scan of the first buffer of data, the SECUNZIP program attempts to locate a valid record terminator character to use throughout the extraction of that file.
107
Note: Unpredictable results may occur if a mix of the control characters X' OA', X' OD', or X' 1A' are found in the input stream. PKZIP uses the first occurrence of one of these characters when automatic detection is used.
For example, in a ZIP archive brought from a standard UNIX platform, the record delimiter is saved as x'0A'. UNZIP processsing dynamically re-defines the DATA_DELIMITER value for the remainder of that file. This is also useful if multiple ZIP Files are contained within the same archive and have differing record delimiters.
Situations may arise in unique platform interchanges or when working with text files from different countries when the default translation table is not adequate. You may select any available translation table by using the TRANSLATE_TABLE_DATA command.
Note: The PKZIPz INSTLIB contains sample JCL and source members to assist in creating customized translate tables.
PKZIPz extracts text records stored in the ZIP archive by examining the data for record delimiter and file terminator indicators. Using these indicators, records are aligned in accordance with the target file attributes.
Data Format - Binary Records
Binary data is stored in the ZIP archive in its original format. Binary data may be graphics or numbers that are already in “computer format”; therefore, no translation is done. The length of binary records in UNZIP processing is determined in one of two ways:
Fixed-length records: PKZIPz automatically fills the available block according to the allocation specifications.
Binary records of variable length: A Record Descriptor Word (RDW) is inserted with the SAVE_LRECL(Y) command. An indicator is tracked in the archive directory that instructs UNZIP processing to automatically use these lengths when extracting the file. Use of this feature is extremely important when processing binary data with varying-length records. Note that the record length is in little-Endian format within the archive, not S390 format.
File Attributes
Within the ZIP archive are two different directories providing information about the files held within the archive.
A local directory included at the front of each file, with information pertaining to it—for example, file size and date ZIPPED.
A central directory located at the end of the ZIP archive. The central directory lists the complete contents of the ZIP archive and is the primary source of information for controlling UNZIP processing.
PKZIPz will optionally store extended attributes about the file that can be useful in re-creating the file during UNZIP processing. These attributes include items such as space allocation,
108
maximum record size, data set organization (VSAM/PDS/SEQ, etc.). Additionally, an optional sub-category of extended attributes is available. Extended attributes for NONVSAM files include record format, DSORG, LRECL, and block size. Extended attributes for VSAM files would include CLUSTER information. File attributes can be displayed by using the ACTION(VIEWDETAIL) command.
PKZIPz enables you to store the extended attributes in the local directory, central directory (recommended), both, or neither. See the Chapter 10 for the specific command for each of these options. Attributes held in the central directory are used by SECUNZIP.
Data Set Name Transformation The ZIP Archive normally holds file information in a platform-independent directory structure. The default format of each ZIP file name looks very much like an ASCII UNIX directory structure. PKZIPz performs a transformation between MVS data set names and ZIP file names during ZIP and UNZIP processing.
The default transformation involves translating MVS EBCDIC characters to/from ASCII in accordance with the translate table specified by the TRANSLATE_TABLE_FILEINFO setting, and altering data set node delimiters (“.” and “(“ for PDS member name designation) to slashes “/”. When a partitioned membername is specified, the trailing “)” is eliminated.
Additional controls are provided to permit renaming of file names during the transformation process. The ZIPPED_DSN command set assists the user in tailoring the filename built during ZIP processing. The UNZIPPED_DSN command and FILENAME_API (user exit program) assist the user in tailoring the MVS name to be used during UNZIP processing.
Large File Considerations
It is best when using the ZIP process for large files to use half-track blocking for the ZIP archive (this is the default size employed by PKZIPz). This method provides the best performance and makes the most efficient use of storage space for ZIP archives and ZIP temporary files. Use of other block sizes decreases the volume of data that can fit onto a single volume and affects performance.
A temporary work file may be created during the updating or reconfiguring of a file in the ZIP archive, depending on file size and available storage. This temporary file may or may not have the same storage attributes as the original file. The temporary file holds the updated form of the file in order to allow for the reformatting of the (new) ZIP archive. To preserve the integrity of the original archive in case of a failure, the old archive is preserved while a new archive is being built. Therefore, there must be enough space allowed to accommodate the size of the old archive, the temporary file, and the updated archive.
109
Determining File Size
Default space allocations may not be adequate when compressing large files. To calculate the space needed for the ZIP archive and the temporary files, the following proportions may be helpful:
ZIP archives - Primary: 25% (one-quarter) of the total size of the uncompressed file(s) (ARCHIVE_SPACE_PRIMARY command).
ZIP archives - Secondary: 10% (one-tenth) of the total size of the uncompressed file(s) (ARCHIVE_SPACE_SECONDARY command).
Temporary Files - Primary: 25% (one-quarter) of the size of the largest uncompressed file (TEMP_SPACE_PRIMARY command).
Temporary Files - Secondary: 10% (one-tenth) of the size of the largest uncompressed file (TEMP_SPACE_SECONDARY command).
If a tape-based archive is used, it is possible to use a temporary disk archive during processing (see STAGE_TAPE_ON_DISK command). The sizes used should correspond to those specified in the tape archive.
110
9 File Processing
File Support
PKZIPz can support files of various formats—specifically: sequential files, PDS, or PDSE members, VSAM files, and magnetic tapes or cartridges. Three applications are possible for each file type:
Compressing files of each format into a ZIP archive.
Data from a ZIP archive may be extracted into each of these formats.
A ZIP archive may be managed in each of these formats.
An overview of information regarding each file type is shown in the table below. Additional information that is required in working with each specific file type is detailed under the appropriate section later in this chapter.
In all cases, PKZIPz will optionally save file type information during ZIP processing. This information may be used by ZIP-compatible products in applicable environments for an equivalent reconstruction of the file during UNZIP processing.
111
Sequential Files PDS or PDSE
Members
VSAM Files Magnetic Tapes/Cartridges
Supported Record Formats
Undefined: U
Fixed: F, FA, FB, FM, FBA, FBM, FBS
Variable: V, VA, VB, VM, VBA, VBM, VS, VBS (see Note)
Undefined: U
Fixed: F, FA, FM, FBA, FBM
Variable: V, VA, VB, VM, VBA, VBM, VS, VBS (see Note)
ESDS
KSDS
RRDS
Same as sequential files for standard-label and non-label tapes.
Supported ZIP Archive Formats
Undefined: U
Fixed: F, FB, FBS
Variable: V, VB
Undefined: U
Fixed: F, FB
Variable: V, VB
ESDS See Magnetic Tapes/Cartridge section later in chapter.
File Selection Methods
File name
File masks
JCL DD cards
ALIAS Path Name
File name
File masks
JCL DD cards
Cluster name
Path name
File masks
JCL DD cards
JCL DD cards (see DD commands used with sequential files).
File names (limited to ZIP processing of cataloged tape files where mount authority is provided).
Note: Spanned Files: Spanned record support for binary files (DATA_TYPE=BINARY) will require the record length (SAVE_LRECL=Y). The maximum record length for a binary file is 32768, the maximum record length for a text file (DATA_TYPE=TEXT) is 32764. IEBCOPY unload files will require DATA_TYPE=BINARY and SAVE_LRECL=Y with a maximum supported record length of 32740.
IEBCOPY PDS UNLOAD REQUIRES THAT THE BLKSIZE OF THE PDSU DATASET (this is the output of the IEBCOPY unload) CAN NOT BE SMALLER THAN THE PDS BLKSIZE +20. THE LARGEST PDS BLKSIZE THAT CAN BE ACCOMMODATED WILL BE 32740. IF THIS IS EXCEEDED A S002 ABEND WILL OCCUR IN PKZIP.
Note: Unless otherwise specified, non-VSAM input/output data sets are restricted to BLKSIZE <= 32760 within the operating characteristics of the active access method.
Sequential Files
In this chapter, the term sequential file means an MVS NON-VSAM data set with DSORG=PS. This includes individual members of a GDG.
Compressing Sequential Files Batch jobs may be submitted to process sequential files using JCL DD cards and/or by file selection specifications made with control statements. Use the INFILE command to reference a data set allocated to the job step with a JCL DD statement. This directs PKZIPz to place the
112
specified file into the archive. Multiple INFILE control statements may be used in a single execution. The files are selected for processing in the order specified by INFILE (not by the sequence of the JCL statements).
//MYFILE DD DISP=SHR,DSN=SYS1.PARMLIB(CLOCK00) //SYSIN DD * -ADD -INFILE(MYFILE) /*
Extracting Records into a Sequential File The default extraction format is a sequential file with dynamic allocation (creation) of the file. When the output file is to be dynamically created by the unzip process, then the OUTFILE space and attribute command settings are merged with any saved attribute information from the source archive to govern the dynamic allocation request.
When a target output file is already allocated to the system, unzip processing attempts to identify and use the pre-allocated DCB attributes for the file (either from the VTOC or JCL DD statement). If attributes are supplied in this manner, be certain to allocate the file the DCB attributes that are consistent with the data to be extracted. The saved file attributes in the source archive and command settings are ignored.
The OUTFILE_DD command may be used to reference a data set for extraction into a sequential file format.
//TARGET DD DISP=(NEW,CATLG),DSN=userid.MY.SEQUENTIAL,UNIT=SYSDA, // SPACE=(CYL,(1,1)),DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920) //SYSIN DD * -EXTRACT -OUTFILE_DD(TARGET) -ARCHIVE(MY.ARCHIVE) /*
Managing a Sequential File ZIP Archive A new sequential archive may be created by use of the ARCHIVE_OUTFILE command with appropriate DCB information in the referenced JCL, or implicitly by specifying ARCHIVE_DSN(ZIP_name) with ARCHIVE_DSORG(PS).
//newarch DD DISP=(NEW,CATLG),DSN=userid.MY.ZIP,UNIT=SYSDA, // SPACE=(CYL,(1,1)),DCB=(RECFM=FB,LRECL=27998,BLKSIZE=27998) //SYSIN DD * -ADD -ARCHIVE_OUTFILE(newarch) userid.MY.JCL(*) <= file to be ZIP’d hlq.*.ASM(*)
Additionally, an existing archive may be read by use of the ARCHIVE_INFILE command.
113
Processing GDGs GDG members are generally treated as individual sequential data sets with their respective fully qualified names. With some restrictions, full GDGs and relative generations can be selected for ZIP processing.
The compression and extraction of GDGs (Generation Data Groups) present unique concerns. These are described in more detail in section “Cataloged Dataset Name and INFILE Request Restrictions” in Chapter 7.
File Concatenation for ZIP Processing It is possible to use INFILE to concatenate multiple files of like attributes—for example, the same RECFM and LRECL. File types may include sequential files (DSORG=PS), fully qualified or relative generations of a GDG, or PDS/PDSE members.
Note that PKZIPz processes the entire concatenation as one file stream and uses the first DSNAME in the concatenation sequence as its basis for saving file attributes in the ZIP archive.
PDS and PDSE Members
Partitioned data sets have a variety of unique characteristics and applications. For this reason, separate sections are dedicated to the following topics:
Selecting PDS/PDSE members for compression.
Extracting data into a PDS.
Managing ZIP archives as PDS members.
Load libraries.
Selecting PDS Members for Compression
PKZIPz operates on individual PDS members as distinct file entities, although a complete PDS or subset of a PDS can be operated on through JCL and control card specifications.
Note: In this section, unless specified otherwise, the term PDS also applies to PDSE.
File Name or File Mask
PKZIPz can compress a single PDS member, multiple PDS members, or all members of one or multiple PDS files by adapting the file selection name. Examples of these options are shown below.
//member1 DD DISP=SHR,DSN=SYS1.PARMLIB(CLOCK00) //SYSIN DD * -INFILE(member1) SYS1.PARMLIB(CLOCK00) <= get a single member by catalog SYS1.PARMLIB(CLOCK*) <= get all members starting with “CLOCK”
114
SYS1.PARMLIB or SYS1.PARMLIB(*) <= get all members SYS1.PARMLIB(*00) <= all members suffixed with “00” MY.PDS(A??SRC) <= any character in 2nd and 3rd positions
DD Statements Batch jobs can be submitted to process PDS members using JCL DD cards. To process only one PDS member, the member name can be used as the file identifier. To process all members of a PDS, the PDS name can be used as the file identifier. To process several members, the INFILE command is used along with the selected member names, or a file mask can be used in place of specific member names.
//pds DD DISP=SHR,DSN=SYS1.PARMLIB //SYSIN DD * -INFILE(pds,CLOCK*,*00,MEMBER6) <= multiple INFILE statements may be used.
Extracting Data into a PDS
PKZIPz allows you to extract files from an archive into either a new or existing PDS. A PDS member that has been compressed into the archive may be extracted into a different PDS. In this case, file attributes for the target PDS can be governed by pre-allocation, JCL, control cards, or extended attributes previously saved in the archive during ZIP processing.
When instructing unzip processing to dynamically create the target PDS, use OUTFILE_DSNTYPE(PDS) along with other OUTFILE space and attribute commands. The PDS name is governed by the use of UNZIPPED_DSN, FILE_EXTENSION, and HIERARCHY(N).
//SYSIN DD * -ARCHIVE(my.zipfile) -EXTRACT -OUTFILE_DSNTYPE(PDS) -OUTFILE_RECFM(FB) -OUTFILE_LRECL(80) -OUTFILE_BLKSIZE(27920) -OUTFILE_SPACE_TYPE(CYLINDERS) -OUTFILE_SPACE_PRIMARY(2) -OUTFILE_SPACE_SECONDARY(1) MY/PDS/MEMBER1 <= this is the archive filename selection to result in MY.PDS(MEMBER1)
When a target output file is already allocated to the system, unzip processing attempts to identify and use the pre-allocated DCB attributes for the file (either from the VTOC or JCL DD statement). In this case, be certain to allocate the file the DCB attributes that are consistent with the data to be extracted. The saved file attributes in the source archive and command settings are ignored. Unzip processing does not alter the existing DCB (LRECL or BLKSIZE) for an existing PDS or PDSE.
Managing ZIP Archives as PDS Members
PKZIPz can maintain a ZIP archive as a PDS member using the ARCHIVE_DSN command along with the PDS and member name. When the archive is created as a member of an existing PDS, the attributes for the PDS are not altered.
115
Load Libraries In most cases, load libraries are extracted only to another OS/390 platform; therefore, PKZIPz is able to process either an individual member or an entire load library. The methods used vary, as described below.
Processing Individual Members Each member of the PDS is maintained as an individual file in the ZIP archive. Both DATA_TYPE(BINARY) and RDW commands should be used to ensure data integrity. In addition to normal data storage, necessary load module directory information is saved in the extended attributes section of the archive directory. During extraction, any individual member can be selected for processing. When recreating the member on extraction, additional information (such as the TTR entry point) is translated by PKZIPz to use when loading the file.
Load Module Control Some information, for example, the NOTELIST used for overlay segments, is not retained in the archive. This may cause inaccuracies upon extraction, as that load module may not be properly restored. To avoid this problem, it is recommended that the load module be placed in a library by itself and that the file be extracted to a library that has the same blocksize, on the same device type, or use the process described below.
Processing Entire Load Library If it is not necessary to select individual members for later extraction, or if the library contains overlay segments or other specialized load modules, an alternate method is recommended.
First, unload the PDS to a sequential file format supported by PKZIPz (such as IEBCOPY, or the TSO command TRANSMIT, which can be run in batch). Then ZIP the sequential file. On extraction, PKZIPz will recreate the sequential file, which can then be reloaded to the PDS with the utility used previously.
Although this method entails an extra step, it allows compression of the entire library, and there are no restrictions placed on individual members of the library.
See pkware.mvs.INSTLIB(IVPVSPAN) for a sample job stream.
VSAM Files
VSAM files are selected and allocated with the use of the IBM Access Method Services utility IDCAMS, as described in the IBM Access Method Services manual. A working knowledge of IDCAMS processing will enhance the effectiveness of managing VSAM data sets with PKZIPz. Control statements and input file characteristics are used to internally generate Access Method Services control statements for dynamic calls to IDCAMS.
PKZIPz makes use of Access Method Services User I/O Routines for SYSIN and SYSPRINT file requests. OEM products and/or Installation-written routines that modify standard IBM processing for these exits should not be active for PKZIP processing.
A sample JOB to demonstrate a ZIP and UNZIP of a VSAM KSDS to a VSAM archive can be found in pkware.mvs.INSTLIB(IVPVSAM).
116
Compressing a VSAM File The cluster name is used when selecting a VSAM file for compression. Attempting to use only the data or index components of the file is likely to result in an unusable file. As with sequential and PDS files, either INFILE (with JCL) or file selection statements may be used to identify VSAM files for processing.
VSAM files often contain a mixture of text and binary data. Therefore, unless it is necessary to translate the data to ASCII, use both the DATA_TYPE(BINARY) and SAVE_LRECL commands.
During ZIP processing, the type of VSAM file requested is determined from the system catalog. Through the use of ATTRIB commands, this information can be retained in the ZIP archive for use during UNZIP processing to reconstruct the cluster.
VIEWDETAIL of a KSDS in an Archive The following VIEWDETAIL shows the ZIP result of a KSDS file:
-ACTION(VIEWDETAIL) ZPAM030I INPUT Archive opened: PKWARE.MVS.IVP.TEMP ZPAM560I ARCHIVE FASTSEEK processing is disabled. ZPAM014I 1 file(s) are in the input Archive. ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE ZPAM013I ****************************************************************** ZPAM001I Filename: RCE/MVS810/IVP/KSDS ZPAM002I File type: BINARY SAVED_LRECL (RDW) ZPAM003I Date/Time: 18-FEB-2006 08:48:00 ZPAM004I Compression Method: Deflate- Super Fast ZPAM005I Compressed Size: 64 ZPAM006I Uncompressed Size: 252 ZPAM007I 32-bit CRC: 874B6B6A LHDR Offset: 0 ZPAM008I Created by: PK zSeries 9.0 ZPAM009I Needed to extract: ZipSpec 2.0 ZPAM301I File Type: VSAM ZPAM307I File Record Size: 100 ZPAM308I File Block Size: 0 ZPAM309I File Volume(s) Used: SUP001 ZPAM331I VSAM Cluster Type: INDEXED ZPAM331I VSAM Cluster Catalog Name: SYSC.USERCAT.VSYSVOL ZPAM331I VSAM Cluster Erase: ERASE ZPAM331I VSAM Cluster Format: INDEXED ZPAM331I VSAM Cluster Free CI Space %: 33 ZPAM331I VSAM Cluster Free CA Space %: 10 ZPAM331I VSAM Cluster Imbed: NOIMBED ZPAM331I VSAM Cluster Key Length: 19 ZPAM331I VSAM Cluster Key Position: 0 ZPAM331I VSAM Cluster Ordered: UNORDERED ZPAM331I VSAM Cluster Avg. Record Size: 80 ZPAM331I VSAM Cluster Max. Record Size: 100 ZPAM331I VSAM Cluster Recovery/Speed: RECOVERY ZPAM331I VSAM Cluster Replicate: NREPL ZPAM331I VSAM Cluster Spanned: NONSPANNED ZPAM332I VSAM Data Name: RCE.MVS810.IVP.KSDS.DATA ZPAM332I VSAM Data Type Space: CYL ZPAM332I VSAM Data Primary Space: 5 ZPAM332I VSAM Data Secondary Space: 2 ZPAM332I VSAM Data Buffer Space: 37376 ZPAM332I VSAM Data CI Size: 18432 ZPAM332I VSAM Data Reuse: REUSE ZPAM332I VSAM Data Share Options: 1,3 ZPAM332I VSAM Data Volume: SUP001
117
ZPAM333I VSAM Index Name: RCE.MVS810.IVP.KSDS.INDEX ZPAM333I VSAM Index Type Space: TRK ZPAM333I VSAM Index Primary Space: 1 ZPAM333I VSAM Index Secondary Space: 1 ZPAM333I VSAM Index CI Size: 512 ZPAM333I VSAM Index Reuse: REUSE ZPAM333I VSAM Index Share Options: 1,3 ZPAM333I VSAM Index Volume: SUP001 ZPAM013I ************************************************************************ ZPAM140I FILES: VIEWED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec) ******************************** BOTTOM OF DATA *********************************
Extracting Data into a VSAM File Before extracting data from a ZIP archive, it is helpful to be aware of what file name and file attributes are being stored for the compressed file. VIEWDETAIL can be used on the archive to verify this information. Unless SAVE_FILE_ATTRIBUTES(NONE) is specified, the PKZIP program saves the cluster definition information in the archive directory. When the SECUNZIP program is run to dynamically recreate the file during EXTRACT processing, it uses the stored file characteristics to define the cluster unless overridden in the control cards. (This includes volume information, so archives being transferred from one system to another, or being restored from an older environment, may require VSAM_DATA_VOLUMES override commands to avoid allocation problems to non-existent volumes.)
Take care when defining or overriding VSAM cluster specifications. Items such as MAX LRECL (the second parameter of VSAM_RECORDSIZE) must be correct in order for the PKZIP program to correctly UNZIP the data to the target cluster.
When extracting records for insertion into a VSAM cluster, the PKZIP program opens the cluster in Load-Mode and attempts a sequential insert strategy. However, if a record key is rejected by VSAM PUT because it is out of sequence, the PKZIP program changes to direct-insert strategy for all subsequent records. This has the two possible negative consequences:
Performance may be severely impacted for large files
Because VSAM handles CI and CA splits differently for direct inserts, the cluster may expand beyond anticipated space requirements, thereby requiring a subsequent re-org, or the extraction may fail due to space constraints
For these reasons, if a large file is being extracted to a keyed VSAM cluster and the source data is not known to be in key sequence, the following procedure is recommended:
1. Extract the file to a sequential dataset.
2. Sort the sequential file by the key field.
3. Use IDCAMS REPRO to load the target cluster.
Standard VSAM PUTs are performed during UNZIP operations. VSAM operating characteristics and limitations will be encountered (such as found during IDCAMS REPRO processing). A common occurrence may be that the defined VSAM CLUSTER may not have sufficient space to load the data due to FREESPACE designations. PKZIPz will report VSAM error and reason code information when these types of events occur.
118
To Overwrite a Current VSAM File When extracting a compressed file to an existing VSAM file, it may be desirable to overwrite the existing file. Use the combined commands of OVERWRITE and VSAM_REUSE to cause the compressed file to replace the current file. File attributes are not changed when processing a file overwrite, so you must assure the compatibility of the compressed file with the file being overwritten.
Note: In accordance with IBM’s rules for REUSABLE clusters, the target cluster must have been defined with the REUSE attribute, otherwise, the open for the file will terminate with the message “ZPFM071E VSAM OPEN Error 000000E8 for File(ddname) A(vsam_cluster_name).”
-ACTION(EXTRACT) -OVERWRITE -VSAM_REUSE(Y) filename_to_be_restored
To Restore a Compressed VSAM File
PKZIPz retains the attributes of a VSAM cluster in the ZIP archive unless otherwise specified. Upon extraction, the file attributes are used to recreate the VSAM file if there is not already an existing file. File attributes can be overridden during extraction by use of commands beginning with VSAM_, VSAM_DATA_, and VSAM_INDEX_ as appropriate.
To Create a New VSAM File A VSAM file can be created from a ZIP file even though the file was not originally a VSAM file, or the file attributes were unknown. By using the MAKEVSAM command, along with any suitable VSAM_… commands, a new VSAM file is created with the appropriate VSAM file attributes.
Using a combination of archive file attributes, the ACZDFLT module defaults and any SYSIN command overrides, PKZIPz generates command input to IDCAMS similar to the example below.
DEF CL(NAME(PKWARE.MVS.IVP.KSDS) INDEXED - BUFSP(37376) CISZ(18432) - ERASE FSPC(33 10) NONSPANNED REUSE NOWRITECHECK - RECSZ(80 100) SHR(1,3) - VOL(TSO001 - ) - NOIMBED NREPL RECOVERY - KEYS(10 4) - ) - DATA(NAME(PKWARE.MVS.IVP. KSDS.DATA) - CYL(5 2) ) - INDEX(NAME(PKWARE.MVS.IVP. KSDS.INDEX) - TRK(6 3) - CISZ(512) - )
Note: PKZIPz may default selected commands from the ACZDFLT module, while IDCAMS may default some file attributes when they are not specified.
119
Managing a VSAM ZIP Archive A VSAM Zip archive supports the ESDS format. The ARCHDSORG(VS) command is used to create the archive. See pkware.mvs.INSTLIB(IVPVSAM) for an example of creating a VSAM archive.
Archive VSAM allocation specifications may be changed by using the ARCHIVE_…and VSAM_…commands. The Access Method Services section of the IBM Manual on the DEFINE CLUSTER command may be consulted for more information.
To Update a VSAM ESDS ZIP Archive
To update a VSAM ZIP archive, PKZIPz creates a new ZIP archive and then deletes the previous archive. If either ARCHTO or ARCHFOR commands were used when the archive was originally created, a problem may occur during the deletion process, as the retention period for the VSAM ZIP archive may still be in operation.
To Process “Sparse” RRDS Files
PKZIPz uses the same process as IDCAMS REPRO to process VSAM RRDS files that contain unused “slots.” In copying the RRDS to a sequential data set, the missing slots are treated as nonexistent. If an RRDS is later created, any missing slots are not included in the new file. As a result, the slot number of some of the copied records may be different from the original.
PKZIPz correctly recreates only those RRDS files with no interspersed empty slots. Variable length and fixed length RRDS files are both processed with this constraint.
Unsupported File Types
PKZIPz does not directly support alternate index files or paths. A VSAM alternate index can be managed in two ways.
One option (recommended) is to process the base cluster and recreate the alternate index at the time of extraction.
The other option is to copy the data to another supported data set type using the alternate index, and then compress the copy. On extraction, reverse the process. This approach maintains the data in the ZIP archive in the same order as it was contained in the alternate index.
Magnetic Tapes and Cartridges
PKZIPz can process cataloged tape files using file names (as specified in the table at the beginning of this chapter) or DD command. When an output file or a non-label tape file is defined by the DD command, it must include DCB information on the DD statement.
Copying a Tape-Based Archive to a Disk File
To enhance performance, PKZIPz can use a temporary data set as an interim measure when reading a ZIP archive from an existing cartridge or tape based archive (governed by the STAGE_TAPE_ON_DISK(Y) command). This will be the normal method for reading a tape
120
(3420). More advanced ZIP formats (covered later in this section) are available for cartridge tape devices to improve performance.
TEMP commands are used to specify the size and format of the temporary data set. If default size options are chosen or if the ZIP archive is very large, it is possible that the temporary data set may not be large enough for the entire ZIP archive. This situation produces x37 abend errors, and invalidates the temporary data set, causing PKZIPz to process the file directly.
Note: Specifically, “tape” refers to Magnetic Tape (3420 style) or Magnetic Cartridge (3480/3490/3590 style). Unless differentiated in the context, the information in this chapter refers to both tape and cartridge.
The //ARCHTEMP DD is used for this procedure. Normally, PKZIPz dynamically allocates this file; however, it is possible to allocate the DD statement directly in the JCL to provide manual control over the allocation of the staging file. Alternatively, the ARCHTEMP file may be allocated as a permanent data set. Using these techniques, the following additional benefits can be obtained:
The permanently staged archive can be used as a backup copy, for example, to maintain GDGs of the archive in a “before” picture
Retains the disk-based archive for subsequent processing runs
More information may be found in Chapter 10 in the section on the command STAGE_TAPE_ON_DISK.
Compressing Data from Tape
PKZIPz processes cataloged standard-label tape files just like disk files (namely, either through data set selection control cards or DD statements with INFILE). However, the file attributes that are stored with the archive for the related file are limited to information such as LRECL, BLKSIZE,and RECFM. When extracting such files to disk, OUTFILE_ commands should be provided either by command or the defaults module to specify proper space allocation information. The use of MULTI_THREAD_LIMIT(1) is required when there are multi file tape data sets on one volume. For example, assume that there are the following files on tape cartridge ZIP000. ZIP.FILE.TEST1 with LABEL=1, ZIP.FILE.TEST2 with LABEL=2, and ZIP.FILE.TEST3 with LABEL=3. In order to compress these files you must specify MULTI_THREAD_LIMIT(1). If you do not you will receive this DARC error:
Dynamic Allocation error (0220) for {ZIP.FILE.TEST2
DARC: Requested volume not available. Ref. IKJ56221I
Non-labeled Tapes (NL)
Non-label tapes do not contain DCB information that is necessary for PKZIPz to process the compression (such as, RECFM, LRECL, and BLKSIZE). This is not an issue when using standard-labeled tapes, as the information is coded in the label. It is imperative that the required information be included in the DD statement, as shown in the example below, otherwise standard system OPEN abends will result.
121
//TAPEIN DD DISP=OLD,DSN=my.tape.file,UNIT=TAPE, // DCB=(RECFM=FB,LRECL=80,BLKSIZE=32720) // LABEL=(1,NL) //SYSIN DD * -ARCHIVE(my.archive) -INFILE(TAPEIN)
Restriction: Non-label (NL) tape data sets should not be selected via control cards, because the DCB information cannot be obtained for the file.
File Attributes The minimal file attributes that are stored for tapes when compressed are DSORG, RECFM, LRECL, and BLKSIZE. These are apparent in the example of archive detail as shown below:
VIEWDETAIL Display
ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE Inc. ZPAM013I ************************************************************** ZPAM001I Filename: userid/TEST/TAPE ZPAM002I File type: TEXT ZPAM003I Date/Time: 18-FEB-2006 08:48:00 ZPAM004I Compression Method: Deflate- Super Fast ZPAM005I Compressed Size: 34 ZPAM006I Uncompressed Size: 247 ZPAM007I 32-bit CRC: 9EBBDFBB ZPAM008I Created by: PK zSeries 9.0 ZPAM009I Needed to extract: ZipSpec 2.0 ZPAM301I File Type: NONVSAM SEQUENTIAL ZPAM303I File Record Format: FB ZPAM307I File Record Size: 80 ZPAM308I File Block Size: 6160 ZPAM309I File Volume(s) Used: SC0016 ZPAM310I File Creation Date: 2006/02/18 ZPAM311I File Referenced Date: 2006/02/18
Extracting Data onto Tape
PKZIPz requires these steps to extract data onto tape.
Specify the ZIP file to extract using an appropriate file selection
Use a DD statement to specify the tape dataset you are extracting to, being sure to include DCB information.
Use the OUTFILE command to extract the ZIP file onto the appropriate tape, as specified in the DD statement.
Restriction: Only one OUTDD statement can be used per job. It is recommended that data sets be extracted to tape one at a time.
Managing a ZIP Archive on Tape
PKZIPz can read or write ZIP archives on tape. Use the ARCHIVE_INFILE and ARCHIVE_OUTFILE commands to specify the tape to be processed.
122
Enhanced Tape (XTAPE) Archive Formats
PKZIPz supports an ARCHIVE_ZIPFORMAT called XTAPE (and an associated XTAPE_LBI). Using this format can significantly improve performance when creating or accessing a tape-based archive. The new format eliminates the need for temporary disk work space to hold a staged archive during the STAGE_TAPE_ON_DISK for an archive access request.
Large Block Interface
PKZIPz supports large block sizes for devices supporting greater than 32760 block sizes. Refer to the sections on the ARCHIVE_BLKSIZE and ARCHIVE_ZIPFORMAT commands for additional information.
To Process Multiple-Volume Tape Archives
A tape archive contains information at the end of the tape that is necessary for PKZIPz processing. PKZIPz scans the tape until it finds the information and then returns to the beginning of the tape to begin processing. Because this necessitates accessing the tape at least twice, one of the following options should be considered to reduce the impact of the tape handling:
Use ARCHIVE_ZIPFORMAT XTAPE or XTAPE_LBI when creating archives that reside on tape cartridges. Advanced tape positioning techniques will reduce the number of tape mounts as well as take advantage of high speed positioning capabilities available in cartridge drives.
Mount all the required tapes at once. This can be done by specifying the unit count parameter on the DD statement (keyword UNIT). For example, if two tape units are to be allocated, the DD statement would read UNIT=(TAPE, 2), thus insuring that both volumes of a 2-volume archive will be mounted.
The UNIT= parameter for any tape file must match the devices defined for the local system. The systems programming staff at the installation should be contacted for information regarding these units and standards for use.
Copy the tape archive to a disk file, and processing the disk instead of tape.
Use TAPETODISK command of SecureZIP for z/OS to copy the archive to disk.
To Compress Data into a ZIP Archive on Tape
With the ARCHIVE_OUTFILE command, PKZIPz compresses data into a ZIP archive residing on tape. Use a DD statement to specify the new tape-based archive data set and include necessary DCB information. The ARCHIVE_OUTFILE command replaces any ARCHIVE_… commands intended to dynamically create an archive, and directs PKZIPz to create the ZIP archive on the tape data set as specified by the name in the DD statement.
//ARCHOUT DD DSN=hlq.archive.zip,UNIT=tape1,DISP=(NEW,CATLG), // DCB=(RECFM,LRECL=32760,BLKSIZE=32760),LABEL=(1,SL) //SYSIN DD * -ARCHIVE_OUTFILE(ARCHOUT)
1 Reference PKZIP Support Notice #13 02/16/2001 regarding LINUX target system support files ld.so-1.9.5-13.i386.rpm and libc-5.3.12-31.i386.rpm.
123
To View a Tape-Based Archive Tape-based archives may be viewed in the same way as disk-based archives. You can use either a DD statement referenced by ARCHIVE_INFILE (with appropriate DCB information if the tape file is non-label) or a cataloged standard-label tape referenced by the ARCHIVE command.
Restriction: Some data centers do not allow dynamic allocation of tape data sets. In this case, use ARCHIVE_INFILE with a DD statement.
Processing Hint: If you intend to VIEW an archive that is in ARCHIVE_ZIPFORMAT(FULL) format and later process it for extraction, you may save the time of re-processing the tape volume(s) by specifying STAGE_TAPE_TO_DISK with an //ARCHTEMP DD statement to direct the SECUNZIP program to create a disk copy of the archive for subsequent processing. The disk archive can then be used for the EXTRACT (or further VIEWing with ISPF).
//ARCHTEMP DD DSN=permanent_dsn,DISP=(NEW,CATLG),UNIT=disk_device DD statement.
The sample JCL below demonstrates the creation of a ZIP archive on tape, followed by a step to view the cataloged tape data set.
//ZIPIT EXEC PGM=PKZIP //SYSPRINT DD SYSOUT=* //ARCHOUT DD DSN=&SYSUID..TAPE.ZIP, // DISP=(NEW,CATLG), // UNIT=(3490,,DEFER), // LABEL=(1,SL), // DCB=(RECFM=FB,LRECL=32760,BLKSIZE=32760) //SYSIN DD * -ARCHIVE_OUTFILE(ARCHOUT) -ACTION(ADD) PKWARE.MVS.INSTLIB(DATASEQ1) /* //VIEWIT EXEC PGM=PKUNZIP //SYSPRINT DD SYSOUT=* //SYSIN DD * -ARCHIVE(&SYSUID.TAPE.ZIP) -ACTION(VIEW) /*
To Extract Data from a Tape-Based Archive A tape-based archive can be specified via ARCHIVE_INFILE (along with necessary DCB information on the associated DD statement for a non-label data set) or with ARCHIVE for a cataloged standard-label data set.
Performance note: Processing a tape-based archive may be faster when specifying STAGE_TAPE_TO_DISK(Y). The reasons are as follows:
The architecture of a ZIP archive (on all platforms for all PKZIP 5.x products and newer) has the central file directory at the back of the archive. This is also where some important file information is kept (such as whether the file is text needing translation, or binary). Therefore, the SECUNZIP program must read the back of the archive before scheduling the processing of the files, and then rewind and read from the beginning.
Because of the serial nature of the tape media, only one task can be used to EXTRACT the data. When many non-partitioned files are being selected for processing, multi-tasking may be beneficial with a disk-based archive.
124
To Update Files in a Tape-Based Archive
PKZIPz requires the use of a new tape to update files residing on a tape-based archive. For this, ARCHIVE_INFILE and ARCHIVE_OUTFILE must be used. The input and output archives do not need to both be of the same media type (one may be disk and the other tape).
125
10 Commands
This chapter describes the commands used by the PKZIPz programs.
PKZIPz can perform various actions in conjunction with the use of the following commands and modifiers:
[–ACTION(ADD|COPY|DELETE|EXTRACT|FRESHEN|UPDATE|VIEW)]
ACTION(ADD) is the default action for ZIP processing, and ACTION(EXTRACT) is the default for UNZIP if none of the above actions is explicitly specified. The actions ADD, COPY, DELETE, FRESHEN, and UPDATE all make logical changes to an archive, while EXTRACT and VIEW only read an existing archive.
Each of the actions requires a ZIP archive to process, so the following commands must always be specified:
–ARCHIVE_DSN(<ZIP dataset name>) –ARCHIVE_INFILE(dd_name)
For details on how to input commands for processing by PKZIPz—for example, SYSIN, PARM parameters, and so on—refer to the section “Command Details,” later in this chapter.
Command Syntax
Command strings and filenames are identified with either a blank or a semi-colon “;” delimiter.
Non-blank characters found in a command buffer that are not identified as a command or comment are treated as a filename selection.
Comments are currently supported when Column1 of an input buffer is an asterisk “*”. Commands are identified by a hyphen “–” either in the first column of a non-continued line, or immediately following a blank or semi-colon. Unpredictable results will occur when unidentified characters are found in the input stream (depending on their location in the command structure).
Command names are accepted in mixed case.
126
Command values which have specifically listed options are translated to upper case to facilitate case-insensitive coding.
Only selected command values which are free-form in nature—for example, MVS file names—are translated to upper case. Others—for example, internal ZIP filenames—retain case sensitivity.
Filename selections are case-sensitive.
File Selections vs. Commands
A PKZIPz command is indicated by placing a “–” (hyphen) character in front of a valid command string. If no “–” character is found at the start of a sequence of characters, the characters are interpreted to be part of a file selection for ZIP or UNZIP processing.
When selecting files for SECUNZIP processing, keep in mind that, due to the heterogeneous nature of ZIP archives, filenames are handled with mixed case. This means that filename selection statements should be coded to match the filename exactly.
When selecting files for SECUNZIP processing, quote (") delimiters are required when there is an embedded blank in the filename to be selected. For example:
"My Documents/readme.txt"
Quote delimiters can also be used when a filename begins with a hyphen (-), to avoid confusion with command syntax.
If no file selection is specified for ZIP processing, the PKZIP program assumes that there are no files to be added or updated and outputs an error message. The PKUNZIP program assumes that all files in the archive are to be processed.
&SYSUID When specifying data set names in commands or filename specifications within the command input stream, the reserved word &SYSUID can be used to represent the 1-7 character user name that the operating system supplies in the address space control block extension for the execution. PKZIPz performs the substitution in the command string before continuing processing. By using this command notation, a generic set of commands can be set up to perform archiving operations for various users.
-ARCHIVE_DSN(&SYSUID.MY.ZIPS(SOURCE)) &SYSUID.MY.COBOL(*)
Summary of Available Commands
The commands listed below are available in both the PKZIP and PKUNZIP programs. Information specific to individual commands appears later in this chapter, in the section “Command Details.” A notation of SZ in the PKZIP or PKUNZIP column of the table indicates that the command or setting is available only with SecureZIP for z/OS.
127
COMMAND DESCRIPTION PKZIP PKUNZIP
<dataset name> Defines the name of a member that should be added to, updated in, or deleted from a compressed ZIP archive. Wildcards can be used to specify generic names.
• •
–ACTION ADD - Used to add files that are not already present in the ZIP archive. This is the default action for the PKZIP program (ZIP default).
COPY - Used to create a subset Archive from files contained in an existing archive.
DELETE - Specifies that selected files be deleted from the old ZIP archive.
EXTRACT - Specifies that selected files be extracted from the ZIP archive. (PKUNZIP program default).
FRESHEN - Specifies that selected files be updated in the old ZIP archive.
TEST - Specifies that the ZIP archive files be tested for integrity.
UPDATE - Used to update files that are already in the ZIP archive or to add files that are not already present in the ZIP archive.
VIEW - Output details of the files selected from the ZIP archive to the SYSPRINT dataset.
• •
ACTIVITY_LOG Defaults-module-only setting to collect program activity information.
• •
–ARCHIVE_BLKSIZE Specifies the block size for a new or updated ZIP archive.
•
–ARCHIVE_COMMENT Allows a comment of up to 255 characters to be specified and saved in the archive central directory.
•
–ARCHIVE_DATACLASS Specifies the DF/SMS data class for a new or updated ZIP archive.
•
–ARCHIVE_DIR_BLOCKS Specifies the directory block amount for a new ZIP archive.
•
–ARCHIVE_DSN Specifies the archive to be read (and updated) by ZIP processing.
• •
–ARCHIVE_DSORG Specifies the dataset organization for a new or updated ZIP archive.
•
–ARCHIVE_FASTSEEK Performance improvement for archive read access.
• •
–ARCHIVE_INFILE Specifies the DDname that references a ZIP archive to be read in by the PKZIP program.
• •
–ARCHIVE_LRECL Specifies the logical record length for a new or updated ZIP archive.
•
128
COMMAND DESCRIPTION PKZIP PKUNZIP
–ARCHIVE_MGMTCLASS Specifies the DF/SMS management class to be used for a new or updated ZIP archive.
•
–ARCHIVE_OUTFILE Specifies a DD statement describing the archive to output to by ZIP processing.
•
–ARCHIVE_RECFM Specifies the record format of a new or updated ZIP archive.
•
–ARCHIVE_SPACE_MULTIVOL Control multi-volume allocation of the archive data set.
•
–ARCHIVE_SPACE_PRIMARY Specify the number of allocation units in the primary extent of a new or updated ZIP archive.
•
–ARCHIVE_SPACE_RLSE Specifies whether free space should be released when the ZIP archive is de-allocated.
•
–ARCHIVE_SPACE_SECONDARY Specifies the number of allocation units in the secondary extent of a new or updated ZIP archive.
•
–ARCHIVE_SPACE_TYPE Specifies how space is to be allocated for a new or updated ZIP archive.
•
–ARCHIVE_STORCLASS Specifies the DF/SMS storage class for a new or updated ZIP archive.
•
–ARCHIVE_TIMESTAMP Specifies which Date/Time option to use in setting the timestamp of a created ZIP file.
•
–ARCHIVE_UNIT Specifies the generic unit for allocation of a new or updated ZIP file.
•
–ARCHIVE_VOLUMES Specifies the volume(s) for allocation of a new or updated ZIP archive.
•
–ARCHIVE_ZIPFORMAT Qualifies the ZIP archive format based on compatibility and performance requirements, as well as whether Large Block Interface should be used for LBI-compatibile devices.
•
–ATTRIB_COMPATIBILITY Governs the type of extended attributes that are stored in the archive.
•
–AUTHCHK Activates digital signature authentication for the archive Directory or Files.
•SZ
–CALLMODE Internal environmental interfacing command. • •
–CHECK_SYSIN_MEMBER Verifies a command input stored in a PDS or PDSE member.
• •
–COMPRESSION_LEVEL Specifies speed and compression level when Zipping a file.
•
–COMPRESSION_METHOD Specifies the compression algorithm to use when compressing a file
–CRLF Controls the use of record delimiters and an optional file terminator.
• •
129
COMMAND DESCRIPTION PKZIP PKUNZIP
–DATA_DELIMITER Specifies the delimiter(s) to be used at the end of each text record of the file.
• •
–DATA_STORAGE Specifies the amount of cache memory used in ZIP processing.
• •
–DATA_TRANS_API_ERRLIM Unused at this time •
–DATA_TRANS_API_ERROR Intended action when a user API program error occurs.
•
–DATA_TRANS_API_LANGUAGE Programming language/linkage used for the DATA_TRANS_API user program.
•
–DATA_TRANS_API_NAME Load module name of User program used to modify data records during PKZIP processing.
•
–DATA_TRANS_API_PARM Data string to be passed to the User API program.
•
–DATA_TRANS_API_TRACE Tracing level for API operation. •
–DATA_TRANS_API_WORKSIZE Size of persistent work area provided by PKZIP to the user program.
•
–DATA_TYPE Specifies that selected files for compression are binary or text. (Can be dynamically detected).
• •
–DATATYPE_DETECT_DEPTH Specifies the distance that a file is scanned before making a determination between binary or text.
• •
–DATATYPE_DETECT_TABLE Specifies the table of characters used to assess whether a byte is text or binary.
• •
–DATATYPE_TEXT_PERCENT Specifies the percentage of the sample that must meet the “text” criteria before it will be TEXT.
• •
DDNAME_PARMLIB Specifies the DDname to use for command input (prior to SYSIN). (Specified in the defaults module only.)
• •
–DDNAME_SYSIN Specifies the DDname to use for command input (unless –NOSYSIN is specified).
• •
–DDNAME_SYSPRINT Specifies the DDname to be used for PKZIPz messages.
• •
–DDNAME_ZPSORTIN During –ACTION(VIEW) processing, SORT is called. This internal SORTIN DD is used.
•
–DDNAME_ZPSORTOUT During –ACTION(VIEW) processing, SORT is called. This internal SORTOUT DD is used.
•
–ECHO Specifies that a copy of PKZIPz commands should be output to the message dataset.
• •
–ENCRYPT_CERT_LIMIT Restricts the number of certificates used for each encrypted file
•
130
COMMAND DESCRIPTION PKZIP PKUNZIP
–ENCRYTPION_METHOD Specifies which encryption algorithm is to be employed.
•
–EXCLUDE(dsname mask) Specifies which files may be eliminated from being processed using a mask selection.
•
–EXTRACT_PREVIEW Specifies that a select number of records be processed for previewing the data.
•
–FACILITY_ENCRYPTDATA Specifies which cryptographic facilities should be used for data encryption.
•SZ •
–FACILITY_HASH Specifies which cryptographic facilities should be used in support of digital signatures and authentication.
•SZ •
–FACILITY_RANDOM Specifies which cryptographic facilities should be used in support of pseudo random data generation (for encryption)
•SZ
–FILE_BUSY_WAITTIME Specifies how long PKZIPz should wait while continually retrying before it will terminate.
• •
–FILE_EXTENSION Specifies what to do with an extension. •
–FILE_TERMINATOR Specifies the character(s) to be stored (or recognized) at the end of the last record of a file.
• •
–FILENAME_API_ERRLIM Unused at this time •
–FILENAME_API_ERROR Intended action when a user API program error occurs.
•
–FILENAME_API_LANGUAGE Programming language/linkage used for the FILENAME_API user program.
•
–FILENAME_API_NAME Load module name of User program used to convert archive File names to MVS Data Set names during EXTRACT processing.
•
–FILENAME_API_PARM Data string to be passed to the User API program.
•
–FILENAME_API_TRACE Tracing level for API operation. •
–FILENAME_API_WORKSIZE Size of persistent work area provided by PKUNZIP to the user program.
•
–FILENAME_ENCRYPTION Perform strong encryption on the archive central directory
•
–FILENAME_SELECT_CASE Affect archive filename selection case sensitivity.
•
–GDGALL_SUPPORT Specifies whether all levels of a Generation Data Group (GDG) are to be retrieved and included in the archive.
•
–GZIP Specifies that the output archive will be created in GZIP format.
• •
131
COMMAND DESCRIPTION PKZIP PKUNZIP
–GZIP_SUFFIX Specifies the name to be used as the last level of the filename when there is no valid GZIP filename.
• •
-GZIPCRC_IGNORE Yes/No switch permitting UNZIP processing for GZIP archive that has superfluous data at the end of the stream due to environmental transfer
•
–HIERARCHY Specifies that the full dataset component hierarchy should be used when converting a filename between ZIP archive format and MVS format.
•
–INCLUDE_CMD Include batched commands from a partitioned library.
• •
–INCLUDE_SFX Create a self-extracting archive •
–INFILE Specifies what file(s) to compress by identifying a DD statement.
•
–INSERT_MEMBER Used to add a member to an existing PDS. •
–KEY_PROTECT_LEVEL Strength of key protection for advanced encrypted archives.
•SZ
–LDAP_ENCRYPT_CERT_SELECT Restricts the number or type of certificates used in encrypting a file.
•SZ
–LICENSE_HLQ Specifies the high level qualifier to be used in locating the License Control Dataset.
• •
LICENSE_WTO_INFO Support console message automation for expiring license. (Specify in the defaults module).
• •
–LMOD_SUPPORT Sets –DATA_TYPE(BINARY),–SAVE_FILE_ATTRIBUTES, and –SAVE_LRECL commands on to allow simultaneous processing of load modules with text files in a PDS
• •
–LOGGING_LEVEL Specifies the level (or quantity) of messages output to SYSPRINT.
• •
–MASTER_RECIPIENT This enables an enterprise to decrypt and access the file(s) when other RECIPIENTs are no longer able or eligible.
•SZ •
–MEMORY_MODEL Specifies where file management control blocks are held and the amount of storage than can be used for compression control tables.
•
–MULTI_THREAD_LIMIT Specifies the number of subtasks to be used in compressing datasets.
• •
–NOAPI The Language Environment CEEPIPI environment associated with User API programs (such as DATA_TRANS_API) will not be initialized.
• •
132
COMMAND DESCRIPTION PKZIP PKUNZIP
–NOSYSIN Specifies the SYSIN dataset is not opened for commands.
• •
–ON_FILE_ACCESS_ERROR Specifies the action to take when an access error has occurred.
• •
–ON_FILE_IO_ERROR Specifies the action to take when an I/O error has occurred.
• •
–OUTFILE_BLKSIZE Specifies the block size for a newly extracted dataset.
•
–OUTFILE_DATACLASS Specifies the DF/SMS data class for a newly extracted dataset.
•
–OUTFILE_DD Specifies what file(s) are to contain the extracted data by identifying a DD statement.
•
–OUTFILE_DIR_BLOCKS Specifies the directory block amount for a newly extracted dataset.
•
–OUTFILE_DSNTYPE Determines the type of output file to be created.
•
–OUTFILE_LRECL Specifies the logical record length for a newly extracted dataset.
•
–OUTFILE_MGMTCLASS Specifies the DF/SMS management class to be used for a newly extracted dataset.
•
–OUTFILE_OVERWRITE Specifies overwrite of an existing file or member within a PDS.
•
–OUTFILE_PDS_ENQ Specifies the level of disposition that will be used for a PDS or PDSE when processing an EXTRACT request.
•
–OUTFILE_RECFM Specifies the record format of a newly extracted dataset.
•
–OUTFILE_SPACE_MULTIVOL Control multi-volume allocation of an Output data set during EXTRACT.
•
–OUTFILE_SPACE_PRIMARY Specify the number of allocation units in the primary extent of a newly extracted dataset.
•
–OUTFILE_SPACE_RLSE Specifies whether free space should be released when a newly extracted dataset is de-allocated.
•
–OUTFILE_SPACE_SECONDARY Specify the number of allocation units in the secondary extent of a newly extracted dataset.
•
–OUTFILE_SPACE_TYPE Specifies how space is to be allocated for a newly extracted dataset.
•
–OUTFILE_STORCLASS Specifies the DF/SMS storage class for a newly extracted dataset.
•
–OUTFILE_UNIT Specifies the generic unit for allocation of a newly extracted dataset.
•
133
COMMAND DESCRIPTION PKZIP PKUNZIP
–OUTFILE_VOLUMES Specifies the volume(s) for allocation of a newly extracted dataset.
•
–PAD_CHAR Specifies the character to use to pad fixed length records when extracting.
•
–PAD_VSAM Specifies that variable length records be padded using the character specified in –PAD_CHAR.
•
PARMLIB_DSNAME_UNZIP Specifies the name of the dataset containing the configuration specifications for UNZIP processing. (Specified in the defaults module only.)
• •
PARMLIB_DSNAME_ZIP Specifies the name of the dataset containing the configuration specifications for ZIP processing. (Specified in the defaults module only.)
• •
PARMLIB_FILE_WAIT_MAX If the specified –PARMLIB_DSNAME cannot be dynamically allocated, this is the amount of time to wait before terminating. (Specified in the defaults module only.)
• •
PARMLIB_FILE_WAIT_TIMER If the specified –PARMLIB_DSNAME cannot be dynamically allocated, this is the amount of time to wait before retrying (up to PARMLIB_FILE_WAIT_MAX. (Specified in the defaults module only.)
• •
–PASSWORD Specifies a password to encrypt/decrypt ZIP archive files.
• •
–PATCH_REPORT Specifies that a report of all patches be produced.
See –ACTION.
• •
–PATH Specifies that only the last component of the dataset component hierarchy should be used when converting a filename between MVS format and ZIP archive format.
•
–PKSUPPRC Allows the return code to be suppressed. • •
–PRESERVE_CMD_SPACES Preserves or removes blanks preceding the “|”.
• •
–PROCESS_ALIAS Specifies whether the alias entries for selected PDS members are to be used.
• •
–RECALL_TO_ZIP Specifies whether DFHSM recall of datasets should occur.
•
–RECIPIENT Identifies the eligible party that may decrypt the file(s)
•SZ •
–RECURSE_LEVELS Specifies whether or not data components beyond those specified should be used in matching with your selection.
•
134
COMMAND DESCRIPTION PKZIP PKUNZIP
–SAVE_FILE_ATTRIBUTES Specifies where file attributes should be stored for datasets in the zip archive; in the central directory only, the Local Directory, both directories, or neither directory.
• •
–SAVE_LRECL Compress/ Decompress a binary file with variable record lengths.
• •
SECUREZIP_CONFIG Specifies a member that contains the cert store configuration commands to be included during processing. (Specify in the defaults module).
• •
–SELECT_CATALOGED_ALIAS Specifies whether aliases are to be supported at time of zipping.
•
–SELECT_FROM_PDS Specifies a PDS dataset from which PKZIPz can obtain members to match user selection parameters that do not match any other dataset.
• •
–SELECT_TAPE Specifies whether tape files are to be retrieved and included in the archive.
•
–SET_ERROR_RC Specifies a firm return code to be passed to the system when an error has been detected.
• •
–SHOW_SETTINGS Displays all current command settings. • •
–SIGN_ARCHIVE Generates a digital signature for the archive central directory
•SZ
–SIGN_FILES Generates a digital signature for the files added to an archive
•SZ
–SIGN_HASHALG Specifies which hashing algorithm to use when requesting a signing operation.
•SZ
–SIGNAL_ZIP64 Specifies return code control when engaging ZIP64 extensions.
•
–SIMULATE Simulates file selection processes, but does not perform actual data manipulation for the files selected.
• •
–SNAP_SYSOUT_CLASS Specifies the SYSOUT class to be used for SNAP dumps (reserved for future use).
• •
–STAGE_TAPE_ON_DISK Specifies input from a sequential device be stored in a temporary dataset.
• •
–STRIP_CHAR Specifies an ending character to be removed from the end of each record before it is zipped.
•
–SUPPRESS_DYNALLOC_MSGS Specifies that the dynamic allocation messages in job log be suppressed.
• •
–SYSPRINT_DCB Specifies the DCB record format to be used for SYSPRINT listings.
•
135
COMMAND DESCRIPTION PKZIP PKUNZIP
SYSPRINT_SYSOUT_CLASS Specifies the JES SYSOUT class that will be used for the SYSPRINT listing. (Specified in the defaults module only.)
• •
–TEMP_BLKSIZE Specifies the temporary block size of a temporary PKZIPz dataset.
• •
–TEMP_DATACLASS Specifies the DF/SMS data class to be used for a temporary ZIP dataset.
• •
–TEMP_MGMTCLASS Specifies the DF/SMS management class to be used for a temporary file allocation.
• •
–TEMP_RECFM Specifies the record format for a temporary ZIP dataset.
• •
–TEMP_SPACE_MULTIVOL Control multi-volume allocation of Temporary work files.
• •
–TEMP_SPACE_PRIMARY Specifies the number of space units to be used in the primary partition of a temporary ZIP dataset.
• •
–TEMP_SPACE_SECONDARY Specifies the number of space units to be used in the secondary partition of a temporary ZIP dataset.
• •
–TEMP_SPACE_TYPE Specifies how space is to be allocated for a temporary ZIP dataset.
• •
–TEMP_STORCLASS Specifies the DF/SMS storage class to be used for a temporary file allocation.
• •
–TEMP_UNIT Specifies the unit to be used for allocation of a temporary ZIP dataset.
• •
–TEMP_VOLUMES Specifies the volume onto which a temporary ZIP dataset should be placed.
• •
–TRACE_TABLE_SIZE Specifies the size of the internal trace table. • •
–TRANSLATE_TABLE_DATA Specifies which translation table to use when converting character sets of text files.
• •
–TRANSLATE_TABLE_FILEINFO Specifies a translation table to be used with file information such as comments, file names, and control information of a ZIP archive.
• •
–TRANSLATION_MODE (Reserved for future use). • •
–UNZIPPED_DSN Specifies a different high-level qualifier for an extracted dataset.
•
–VSAM Specifies whether VSAM files should be used orignored when selecting files for compression and using wildcards.
•
–VSAM_ACCOUNT Specifies the accounting information to be provided to Access Methods Services during a DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
136
COMMAND DESCRIPTION PKZIP PKUNZIP
–VSAM_ATTEMPTS Specifies the number of password attempts that are permitted to Access Methods Services during a DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_AUTH_EP Supplies the entry point of a user security verification routine to Access Methods Services during a DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_AUTH_STRING Supplies a string of information to be passed to your security verification routine to Access Methods Services during a DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_BUFFERSPACE Specifies the BUFFERSPACE parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_CATALOG Specifies the CATALOG parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_CISIZE Specifies the CONTROLINTERVALSIZE parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_CLUSTER_TYPE Specifies the file type to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_CODE Supplies a code name for the cluster or component to Access Methods Services during a DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_CONTROLPW Specifies the CONTROLPW parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_DATA_CISIZE Specifies the CONTROLINTERVALSIZE parameter to the data component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
137
COMMAND DESCRIPTION PKZIP PKUNZIP
–VSAM_DATA_EXCEPTIONEXIT Specifies the EXCEPTIONEXIT parameter to the data component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_DATA_FILE Specifies the FILE parameter to the data component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_DATA_NAME Specifies the NAME parameter to the data component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_DATA_ORDERED Specifies the ORDERED parameter to the data component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_DATA_PRIMARY Specifies the primary space allocation value to the data component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_DATA_SECONDARY Specifies the secondary space allocation value to the data component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_DATA_SPACE_TYPE Specifies the space allocation type parameter to the data component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_DATA_VOLUMES Specifies the VOLUMES parameter to the data component of an IDCAMS DEFINE CLUSTER command, used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_DATACLASS Specifies the DF/SMS data class to be used for the creation of a new (or update of an existing) VSAM-defined ZIP archive.
• •
–VSAM_DUPLICATE_ERROR Specifies the action to be taken on realization of a duplicate key when creating a new extracted VSAM dataset.
•
–VSAM_ERASE Specifies the ERASE parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
138
COMMAND DESCRIPTION PKZIP PKUNZIP
–VSAM_EXCEPTIONEXIT Specifies the EXCEPTIONEXIT parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_FILE Specifies the FILE parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_FOR Specifies the FOR parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_FREESPACE_CA Specifies the FREESPACE parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_FREESPACE_CI Specifies the FREESPACE parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_IMBED Specifies the IMBED parameter of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_ATTEMPTS Specifies the number of password attempts that are permitted to Access Methods Services during a DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_AUTH_EP Supplies the entry point of a user security verification routine to Access Methods Services during a DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_AUTH_STRING Supplies a string of information to be passed to your security verification routine to Access Methods Services during a DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_CISIZE Specifies the CONTROLINTERVALSIZE parameter to the INDEX component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_CODE Supplies a code name for the cluster or component to Access Methods Services during a DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
139
COMMAND DESCRIPTION PKZIP PKUNZIP
–VSAM_INDEX_CONTROLPW Specifies the CONTROLPW parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_EXCEPTIONEXIT Specifies the EXCEPTIONEXIT parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_FILE Specifies the FILE parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_MASTERPW Specifies the MASTERPW parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_NAME Specifies the NAME parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_ORDERED Specifies the ORDERED parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_PRIMARY Specifies the primary space allocation parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_READPW Specifies the READPW parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_SECONDARY Specifies the secondary space allocation parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_SPACE_TYPE Specifies the space allocation type parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
140
COMMAND DESCRIPTION PKZIP PKUNZIP
–VSAM_INDEX_UPDATEPW Specifies the UPDATEPW parameter to the index component of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_INDEX_VOLUMES Specifies the VOLUMES parameter to the index component of an IDCAMS DEFINE CLUSTER command, used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_KEYS Specifies the KEYS parameter for an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_MASTERPW Specifies the MASTERPW parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_MGMTCLASS Specifies the DF/SMS management class to be used for the creation of a new (or update of an existing) VSAM-defined ZIP archive.
•
–VSAM_MODEL Specifies the MODEL parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_ORDERED Specifies the ORDERED parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_OWNER Specifies the OWNER parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_READPW Specifies the READPW parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_RECORDSIZE Specifies the RECORDSIZE parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_RECOVERY_OPT Specifies the SPEED or RECOVERY parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_REPLICATE Specifies the REPLICATE parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
141
COMMAND DESCRIPTION PKZIP PKUNZIP
–VSAM_REUSE Specifies the REUSE|NOREUSE parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_SHAREOPTIONS Specifies the SHAREOPTIONS parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_SPACE_PRIMARY Specifies the number of allocation units to be allocated in the primary extent of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_SPACE_SECONDARY Specifies the number of allocation units to be allocated in the secondary extent of an IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_SPACE_TYPE Specifies the type of allocation units to be allocated in the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_SPANNED Specifies the SPANNED|NONSPANNED parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update anexisting) VSAM-defined ZIP archive.
• •
–VSAM_STORCLASS Specifies the DF/SMS storage class to be used for the creation of a new (or update of an existing) VSAM-defined ZIP archive.
•
–VSAM_TO Specifies the TO parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–VSAM_UPDATEPW Specifies the UPDATEPW parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
•
–VSAM_WRITECHECK Specifies the WRITECHECK|NOWRITECHECK parameter to the IDCAMS DEFINE CLUSTER command used to create a new (or update an existing) VSAM-defined ZIP archive.
• •
–ZIPPED_DSN Specifies what parameters to use in converting MVS file names to ZIP file names.
•
–ZIPPED_DSN_SEPARATOR Specifies what separator to use in the new ZIP archive name.
•
142
Command Details
Descriptions of PKZIPz commands are given below in alphabetic sequence. If applicable, synonyms for each command are listed directly below the command.
<dataset name> The <data set name> is an individual name or a file mask of files that are to be used in the ZIP or UNZIP process. The specification may represent one or more files when wildcard masks are used or RECURSE_LEVELS is specified.
Note: This command does not use a “–” prefix.
Pathnames may be specified in the <data set name> and may be either in MVS format (MYFILES.PROJECT.DATA), where periods separate the qualifiers, or in UNIX format and use slashes (MYFILES/PROJECT/DATA). PKZIPz stores the <data set name> in the latter format to provide cross-platform compatibility but accepts references to <data set name> in MVS format.
Note: When standard ZIP archives are requested, a filename may be of mixed case. When GZIP is requested, all characters in the filename should be lower case, according to GZIP specifications.
Formatting For individual data sets or PDS names, the <data set name> entry consists of:
dataset level[.dataset level][.dataset level]….
For example: mydata.testing.temp.
For PDS members, the <data set name> entry consists of:
dataset level[.dataset level][.dataset level] ... (member1[,member2][,member3]…)
For example: mydata.testing.temp(firstrun,secondrun).
When a single data set level is specified either as a data set or a PDS member, and if SELECT_FROM_PDS is present, the associated PDS is identified.
If SELECT_FROM_PDS is not present, then the single level will be identified as a high-level qualifier.
Wildcards Wildcard characters enable you to use a single name, containing wildcard characters, to specify multiple data sets. The wildcard characters (?, *, and **) are used in place of some or all of the characters in the name. They operate as “wild cards” in that they match a range of things instead of just a single character.
143
Wildcards cannot be used in the highest data set level of the data set name.
The more general the wildcard specifications, the longer the file search. To save time, be as specific as possible in selecting data set names.
Question Mark (?)
A question mark (?) represents any single character in that position within a data set level.
For example, MBS.?ABC matches every data set that has one character preceding ABC in its data set level. For example:
MBS.1ABC
MBS.2ABC
MBS.MABC
MBS.??ABC includes data sets that have two characters before ABC in the data set level. For example:
MBS.10ABC
MBS.XXABC
MBS.1JABC
Asterisk *
An asterisk (*) matches any string of zero or more characters in that position, within the level.
For example, JEH.*.SUB matches all data sets of any second level and a third level of SUB data sets. For example:
JEH.BVC.SUB
JEH.TRIAL.SUB
JEH.UNVTEST.SUB
JEH.A*.SUB represents all data sets with a third level of .SUB and all second levels whose names begin with A. For example:
JEH.ABC.SUB
JEH.AQZAR.SUB
JEH.ATEST.SUB
BOOT.* represents all data sets with a first component of BOOT plus any of its second levels. It does not represent data sets with more than one level (see ** for more than one). For example:
BOOT.MINE
BOOT.DATA
BOOT.TESTING
but not
BOOT.MINE.SOURCE
144
JEH.*.D* represents all files within JEH with D beginning with its third level. For example:
JEH.OWN.DATA
JEH.SOURCE.DELIM
JEH.BAKER.DEMO
Double Asterisk **
A double asterisk (**) matches all occurrences of one or the next two data set levels.
For example, ABC.** represents all data sets beginning with ABC and includes the next level or two, if present. For example:
ABC.GROUP.TEST
ABC.GROUP
ABC.MINE
ABC.**.DATA represents data sets with the first level of ABC followed by one or two levels and ending with DATA as the last level. For example:
ABC.GROUP.BASIC.DATA
ABC.GROUP.DATA
ABC.MINE.DATA
MS-DOS and UNIX file formats Data set names are supported in MS-DOS and UNIX formats to delete or view entries. For all other operations, data set names should be in the MVS format.
For UNIX or MS-DOS formatting:
[pathname][/pathname]…[/pathname][/filename]
For MS-DOS formatting:
[pathname][\pathname]…[\pathname][\filename]
Command Icon Legend The following legend is used to identfy icons that may be associated with a given command.
These icons provide platform information, command compatibility, and a icon indicates that you should proceed with extreme caution and double check that the information provided works with your platform. It is important that you double check a command before using it.
145
Icons Description
This icon specifies what platforms use this command.
This command is not compatible with UNIX, iSeries, OS/400, and Windows.
This icon is a warning and it instructs you to read the information and proceed with caution.
–ACTION
Synonyms Include: –ADD, –COPY, –DELETE, –EXTRACT, –FRESHEN, PATCH_REPORT, TEST, –UPDATE, –VIEW
The ACTION command is used to add, copy, delete, extract, freshen, update, or view files in a ZIP archive. It may also be used to view a patch report.
–ACTION(ADD|COPY|DELETE|EXTRACT|FRESHEN|PATCH_REPORT|TEST| UPDATE|VIEW)
ADD - Specifies the addition of a file(s) to a ZIP archive using the method as specified in COMPRESSION_METHOD. If a file already exists in the archive with the same name, the addition will be disallowed and an UPDATE modifier will be required.
Use ARCHIVE_DSN or a combination of ARCHIVE_INFILE and ARCHIVE_OUTFILE along with the ACTION(ADD) to create the new ZIP archive.
The ADD command forces creation of a new ZIP archive.
ADD is the default action for the PKZIP program.
COPY - Specifies that designated files (all by default) are to be copied from one archive to another when running program PKZIP. Data set name selections are accomplished the same as they are with ACTION(DELETE) defined previously. When no names are specified, all files within the input archive are copied to the target. No action is taken if the target archive is the same as the source archive.
Use of ARCHIVE_DSN in conjunction with COPY causes an implicit deletion of all files not selected from the designated archive. This can be a more efficient way to delete files from an archive than by listing them all with DELETE. PKZIP does not allow implicit deletion of all files within an archive when using COPY.
When ARCHIVE_INFILE is used with COPY, PKZIP allows the creation of an empty target archive if none of the requested files matches the input archive.
DELETE - Specifies that the file(s) selected by the <data set name> command be deleted from an existing ZIP archive. This action results in the creation of a new archive, minus the deleted files.
Use ARCHIVE_DSN (or a combination of ARCHIVE_INFILE and ARCHIVE_OUTFILE) along with the ACTION(DELETE) to create the new ZIP archive.
146
The DELETE command forces the creation of a new ZIP archive minus the deleted files.
EXTRACT - Specifies that items or files are looked for in the archive, are brought out, and are put into an MVS data set. EXTRACT is the default action for the PKUNZIP program.
FRESHEN - Specifies that files already existing in an archive are to be replaced by different files having the same names. Note that timestamp verification does not occur, so it is possible to replace a file with one that is older.
PATCH_REPORT - When gathering information for problem analysis, PKZIPz Technical Support may request the output from an execution with PATCH_REPORT. The report output is sent to the designated DDNAME_SYSPRINT standard output. No other commands are required.
PATCH_REPORT is normally executed in batch, although a foreground report can be generated with the ISPF panels.
Note: The PATCH_REPORT command may be used under either PGM=PKZIP or PGM=PKUNZIP. No archive actions will be performed when this command action is selected.
TEST - Specifies that the ZIP archive files be tested for integrity.
This command performs the same functions as an ACTION(EXTRACT) command without actually extracting data or producing a decompressed file. The stored CRC is checked in this process, and a confirmation message occurs in the SYSPRINT data set for each valid file.
Use ARCHIVE_DSN or ARCHIVE_INFILE with this command to specify the ZIP archive to be validated.
UPDATE - Specifies the update or addition of a file(s) to an existing ZIP archive.
VIEW - Specifies that information about selected files be displayed in SYSPRINT. The VIEW command may be used with or without parameters. All parameter fields are optional but, if specified, must be specified in the following order:
VIEW[level][sort][REVERSE][COMMENT]
Level - This parameter specifies the amount and format of the information to be displayed.
Null - If no level is specified, a standard report of one line per file (wrap lines may be inserted for the file name or comment) will be displayed with columnar headings for the field values.
BRIEF - Provides a minimum of information about the files selected for display.
DETAIL - Provides a full set of technical details about the files selected for display.
Sort - Determines the presentation sequence of information in the output report.
NAME - Sort by filename only.
DATE - Sort by date only.
LENGTH - Sort by length of the uncompressed file only.
OFFSET - Sort by order of occurrence within the ZIP archive (first in, first out). This is the default sort sequence.
147
PERCENT - Sort by compression percentage, only.
SIZE - See Length.
REVERSE - Optional switch that reverses the order in which files are normally displayed for the sort criterion specified. For example, a NAME sort normally displays files in ascending order. NAMEREVERSE displays the files in descending order by file name.
COMMENT - Optional parameter that lists any internal comment information in the archive directory in a separate line for each associated file. These file-specific comments are different from the ARCHIVE_COMMENT, which applies to the entire archive.
The following table lists the valid ACTION(VIEW) options:
148
VIEWBRIEF
VIEWBRIEFCOMMENT
VIEWBRIEFDATE
VIEWBRIEFDATECOMMENT
VIEWBRIEFDATEREVERSE
VIEWBRIEFDATEREVERSECOMMENT
VIEWBRIEFLENGTH
VIEWBRIEFLENGTHCOMMENT
VIEWBRIEFLENGTHREVERSE
VIEWBRIEFLENGTHREVERSECOMMENT
VIEWBRIEFNAME
VIEWBRIEFNAMECOMMENT
VIEWBRIEFNAMEREVERSE
VIEWBRIEFNAMEREVERSECOMMENT
VIEWBRIEFOFFSET
VIEWBRIEFOFFSETCOMMENT
VIEWBRIEFOFFSETREVERSE
VIEWBRIEFOFFSETREVERSECOMMENT
VIEWBRIEFPERCENT
VIEWBRIEFPERCENTCOMMENT
VIEWBRIEFPERCENTREVERSE
VIEWBRIEFPERCENTREVERSECOMMENT
VIEWBRIEFREVERSE
VIEWBRIEFREVERSECOMMENT
VIEWBRIEFSIZE
VIEWBRIEFSIZECOMMENT
VIEWBRIEFSIZEREVERSE
VIEWBRIEFSIZEREVERSECOMMENT
VIEWCOMMENT
VIEWDATE
VIEWDATECOMMENT
VIEWDATEREVERSE
VIEWDATEREVERSECOMMENT
VIEWDETAIL
VIEWDETAILCOMMENT
VIEWDETAILDATE
VIEWDETAILDATECOMMENT
VIEWDETAILDATEREVERSE
VIEWDETAILDATEREVERSECOMMENT
VIEWDETAILLENGTH
VIEWDETAILLENGTHCOMMENT
VIEWDETAILLENGTHREVERSE
VIEWDETAILLENGTHREVERSECOMMENT
VIEWDETAILNAME
VIEWDETAILNAMECOMMENT
VIEWDETAILNAMEREVERSE
VIEWDETAILNAMEREVERSECOMMENT
VIEWDETAILOFFSET
VIEWDETAILOFFSETCOMMENT
VIEWDETAILOFFSETREVERSE
VIEWDETAILOFFSETREVERSECOMMENT
VIEWDETAILPERCENT
VIEWDETAILPERCENTCOMMENT
VIEWDETAILPERCENTREVERSE
VIEWDETAILPERCENTREVERSECOMMENT
VIEWDETAILREVERSE
VIEWDETAILREVERSECOMMENT
VIEWDETAILSIZE
VIEWDETAILSIZECOMMENT
VIEWDETAILSIZEREVERSE
VIEWDETAILSIZEREVERSECOMMENT
VIEWLENGTH
VIEWLENGTHCOMMENT
VIEWLENGTHREVERSE
VIEWLENGTHREVERSECOMMENT
VIEWNAME
VIEWNAMECOMMENT
VIEWNAMEREVERSE
VIEWNAMEREVERSECOMMENT
VIEWOFFSET
VIEWOFFSETCOMMENT
VIEWOFFSETREVERSE
VIEWOFFSETREVERSECOMMENT
VIEWPERCENT
VIEWPERCENTCOMMENT
VIEWPERCENTREVERSE
VIEWPERCENTREVERSECOMMENT
VIEWREVERSE
VIEWREVERSECOMMENT
VIEWSIZE
VIEWSIZECOMMENT
VIEWSIZEREVERSE
VIEWSIZEREVERSECOMMENT
149
ACTIVITY_LOG
Synonyms Include: N/A
Only applicable when running a Demonstration Product Key
ACTIVITY_LOG=dataset
This setting is specified in the defaults module only.
When a Demonstration Key is active for the product, certain activities are written to the pre-allocated sequential data set specified by this setting. Reference the Systems Administration Guide for more information.
–ARCHIVE_BLKSIZE
Synonyms Include: –ARCHBLKSIZ
This command works with ARCHIVE_ZIPFORMAT to determine the data set block size for a new non-VSAM archive.
For a new or updated ZIP archive specified through the –ARCHIVE_DSN command, the block size may be requested using the ARCHIVE_BLKSIZE command. Either an explicit value or ZIP-determination request may be made. (See Dynamic Non-LBI archive block size determination below)
For a non-LBI archive written with ARCHIVE_OUTFILE and an associated DD DCB statement, this parameter is ignored. However, LBI-enabled archive processing will honor values in this command. (See JCL DD Non-LBI archive block size determination below)
–ARCHIVE_BLKSIZE(<block size>|DYNAMIC|OPTIMUM|MAXIMUM|SMS)
<block size> - A non-zero numeric BLKSIZE specification request for a dynamically allocated archive (with –ARCHIVE_DSN). A value of “0” is treated as “DYNAMIC”. LBI processing ignores the Block Size Limit value in effect for the run from system parameters. A <block size> may be specified in K kilobytes or as an explicit number of bytes. For kilobytes, the numeric value preceeding the K is multiplied by 1024 to calculate the BLKSIZE to be used. Examples: 4K=4096, 32K=32768, 64K=65,536, 256K=262,144.
DYNAMIC – Allow the block size to be dynamically determined. LBI processing is limited by the Block Size Limit value in effect for the run from any source. This is the recommended setting for general-purpose operation and allows system-administered settings to be enabled.
OPTIMUM – Allow the block size to be dynamically determined with a device-preferred block size. LBI processing is limited by the Block Size Limit value in effect for the run through JCL DD BLKSZLIM.
150
MAXIMUM – Allow the block size to be dynamically determined at the maximum supported level for the device and access method. LBI processing is limited by the Block Size Limit value in effect for the run through JCL DD BLKSZLIM.
SMS – Allow the block size to be dynamically determined in accordance with DYNAMIC. This value is retained for compatibility with prior releases.
Usage Notes
When an update operation is being performed for an existing archive (ACTION ADD, FRESHEN, UPDATE, COPY or DELETE) and no command value is provided for -ARCHIVE_BLKSIZE, the new allocation attempts to retain the DCB attributes from the input archive.
Block size requests must agree with ARCHIVE_ZIPFORMAT LBI-enablement specifications.
For the dynamic allocation of non-LBI format archives with ARCHIVE_ZIPFORMAT(FULL), an ARCHIVE_BLKSIZE of 0, DYNAMIC, OPTIMUM, or SMS attempts to allocate a half-track allocation with a 3390 bias.
If using a PDS or sequential archive, and a block size of 0 is specified, the program determines the block size. (In accordance with IBM DFSMS: Using Datasets, “System Determined Blocksize” is not provided by the operating system for RECFM=U data sets.)
The use of SMS Dataclass with the Extended-format attribute for sequential data sets causes the system to add a 32-byte suffix to each block (see DFSMS “Using Data Sets” under “Selecting Data Set Options; Block Size”), thereby reducing the efficiency of storage. When SecureZIP dynamically allocates an archive, it detects when striped allocation has occurred and reduces the data block size when half-track blocking would be exceeded. However, when a JCL DD (or pre-allocation) is used with ARCHIVE_OUTFILE, SecureZIP honors the resolved BLKSIZE without performing a reduction.
When writing LBI-enabled archives and allowing ZIP to determine the blocksize, the ARCHIVE_BLKSIZE is restricted by both the device maximum and effective Block Size Limit specification (whether by JCL, SMS Dataclass “Block Size Limit”, or PARMLIB(DEVSUPxx) TAPEBLKSZLIM keyword). However, the Block Size Limit may be exceeded by specifying a numeric value that is between the effective Block Size Limit value and the device maximum.
Dynamic Non-LBI Archive Block Size Determination
The following table illustrates the resulting BLKSIZE value for various requests and conditions when requesting dynamic allocation of an output archive. (Further refinements to the final block size may be made due to RECFM requirements.)
151
Initial BLKSIZE Request Other Attributes Resulting RECFM=U Block Size
ARCHIVE_BLKSIZE
0
“DYNAMIC”
“OPTIMUM”
“SMS”
None
27,998
ARCHIVE_BLKSIZE
0
“DYNAMIC”
“OPTIMUM”
“SMS”
SMS Dataclass Extended-format 27,966
ARCHIVE_BLKSIZE
1 - 32,760
None ARCHIVE_BLKSIZE
ARCHIVE_BLKSIZE
27,967 - 32,760
SMS Dataclass Extended-format ARCHIVE_BLKSIZE – 32
ARCHIVE_BLKSIZE
<= 27,966
SMS Dataclass Extended-format ARCHIVE_BLKSIZE
ARCHIVE_BLKSIZE
“MAXIMUM”
None
32,760
ARCHIVE_BLKSIZE
“MAXIMUM”
SMS Dataclass Extended-format 32,728
JCL DD Non-LBI Archive Block Size Determination
The following table illustrates the resulting BLKSIZE value for various requests and conditions when specifying output archive attributes through JCL DD.
The user is required to ensure that RECFM and LRECL attributes are consistent with the BLKSIZE.
When using non-LBI ARCHIVE_ZIPFORMAT values, BLKSIZE reference values should be specified <= 32,760.
Initial BLKSIZE Request Other Attributes Resulting RECFM=U Block Size
ARCHOUTDD
DD BLKSIZE=0, or > 32760
None 27998
ARCHOUTDD
DD BLKSIZE=X, ( <= 32760)
None DD BLKSIZE
152
LBI Archive Block Size Determination
Large Block Interface processing is a unique extension to sequential data set handling. It carries additional processing requirements, controls and limitations in accordance with DF/SMS specifications. PKZIPz resolves the LBI block size to use in a way that is similar to DF/SMS System-Determined Blocksize (Ref: IBM DF/SMS “Using Data Sets”). Data set attribute assignments are based on the following:
LBI data sets must be RECFM=U; therefore PKZIPz automatically changes to ARCHIVE_RECFM=U when ARCHIVE_ZIPFORMAT requests LBI processing.
LBI data sets must result in a block size >= 32,760.
An attempt to use BLKSZLIM on the ARCHOUT DD JCL statement that is < 32,760 results in a system JCL error: “IEF825I INVALID CHARACTER IN THE BLKSZLIM FIELD”
LBI data set block size is not assigned through the BLKSIZE DCB attribute (which is limited to 32,760). Rather, it uses a combination of device-dependent and configurable Block Size Limit values to determine the greatest allowable size. PKZIPz provides control extensions through ARCHIVE_BLKSIZE both for dynamically allocated archive data sets and for JCL DD allocations.
Special ARCHIVE_BLKSIZE values have the following meanings
o MAXIMUM – The requested block size is set to the device Maximum. Honors ARCHIVE_OUTFILE JCL DD BLKSZLIM step override but ignores system Block Size Limits from SMS Dataclass or system PARMLIB.
o OPTIMUM – The requested block size is set to the device Optimum. Honors ARCHIVE_OUTFILE JCL DD BLKSZLIM step override but ignores system Block Size Limits from SMS Dataclass or system PARMLIB.
The requested block size is initially limited by the first non-zero value encountered from the following list:
1. If ARCHIVE_OUTFILE is used, BLKSZLIM on the referenced DD statement, regardless of ARCHIVE_BLKSIZE setting
2. ARCHIVE_BLKSIZE non-zero numeric value, which effectively acts as a dynamic version of BLKSZLIM
3. Block Size Limit from an associated SMS Data Class when ARCHIVE_BLKSIZE is DYNAMIC, SMS or not provided
4. Block Size Limit defined in the system PARMLIB(DEVSUPxx) TAPEBLKSZLIM keyword when ARCHIVE_BLKSIZE is DYNAMIC or SMS or not provided
If an initially limited block size request exceeds a device Maximum value, or if no requested block size can be identified, the device Optimum value is substituted. Note: IBM recommends the use of the Optimum value for a device.
If a device is not LBI-capable, a non-LBI 32,760 block size is substituted, and a non-LBI ARCHIVE_ZIPFORMAT is set.
The following table illustrates the resulting block size for various LBI processing requests and conditions:
153
REQUEST_SIZE BLKSZLIM Device Max Resulting Block Size
1…<=32760 NA *ANY* Use REQUEST_SIZE
Reverts to “FULL” without LBI
0 0 32760 Use Dev Max 32760
0 0 > 32760 Use Dev Optimum
“OPTIMUM” No DD BLKSZLIM *ANY* Use Dev Optimum
“MAXIMUM”
No DD BLKSZLIM *ANY* Use Dev Maximum
“OPTIMUM” “MAXIMUM” DD BLKSZLIM >= BLKSZLIM Use BLKSZLIM
0, “SMS”, “DYNAMIC” <= Dev Max from any source *ANY* Use BLKSZLIM
0, “SMS”, “DYNAMIC” > Dev Max *ANY* Use Dev Optimum
0, “SMS”, “DYNAMIC” 0 *ANY* Use Dev Optimum
>32760
< BLKSZLIM
< Dev Max
<= Dev Max *ANY* Use REQUEST_SIZE
>32760
> BLKSZLIM
< Dev Max
*ANY* *ANY* Use REQUEST_SIZE
>32760
> BLKSZLIM
> Dev Max
*ANY* *ANY* Use Dev Optimum
–ARCHIVE_COMMENT
Synonyms Include: N/A
This command allows a comment of up to 255 characters to be specified and saved in the archive central directory.
–ARCHIVE_COMMENT(<comment>)
comment - A free-form descriptive field that may be up to 255 characters in length and may contain lower-case letters.
-ARCHIVE_COMMENT(This is a sample of a long command input value, and a hyphen illustrates the use of the continuation character for a lon- …..g command.) The hyphen causes a concatenation without blanks.
154
–ARCHIVE_DATACLASS
Synonyms Include: –ARCHDCLASS
For a new or updated ZIP archive, the SMS data class may be specified using the ARCHIVE_DATACLASS command. If the command is not specified, no data class is used in the allocation request.
Allocation of files in a SMS environment is controlled by the installation through automatic class selection routines as defined by the local storage administrator. Control cards specifying SMS classes and/or volume selection may be ignored by the system when performing allocations. Check with the systems administrator for proper designations of these values.
–ARCHIVE_DATACLASS(<data class>)
data class - Names the SMS data class where the updated or new archive is to reside. There is an 8-character limit.
The following parameter option for SMS classes accommodates earlier PKZIP releases:
_NONE_
For example:
ARCHIVE_DATACLASS=_NONE_
An ACZDFLT parameter of _NONE_ maintains the behavior of earlier releases of PKZIP (pre-5.6) for SMS specifications.
Note that when PKZIP dynamically allocates an archive data set, an installation SMS ACS routine may assign a DATACLASS outside of PKZIP’s control. The _NONE_ specification negates the DYNALLOC (SVC99) parameter request for DATACLASS by PKZIP, but the installation can still generate an override. This has the potential for assigning DCB attributes that are incompatible with later processing of the archive data set. Care should be taken when using SMS data class attributes to ensure that the installation assigns correct values (or does not assign them at all).
–ARCHIVE_DIR_BLOCKS
Synonyms Include: –ARCHDIRBLKS, –ARCHIVE_DIRBLKS
For a new ZIP archive, the number of directory blocks may be specified using the ARCHIVE_DIR_BLOCKS command. The default of 56 is not used with ARCHIVE_DATACLASS.
Use ARCHIVE_DIR_BLOCKS in conjunction with an ARCHIVE_DSN when creating a new PDS.
–ARCHIVE_DIR_BLOCKS(<dir blocks>)
dir blocks - This indicates the number of directory blocks for the new ZIP archive. The default allocation is 56 blocks.
155
–ARCHIVE_DSN
Synonyms Include: –ARCHIVE, –ARCHIVE_DSNAME
In PKZIP Processing The ARCHIVE_DSN command specifies the archive name to be read in and updated by PKZIPz. Either this command or the ARCHIVE_INDD command must be used to identify an archive. ARCHIVE_INDD does not allow updating and is used in conjunction with ARCHIVE_OUTDD. There is no default.
–ARCHIVE_DSN(<archname>)
archname - This is the complete archive data set name of the ZIP archive. If the archive is a PDS archive, the member name must be included here.
If archname exists:
PKZIPz performs a SYSTEM ENQ to lock out other users from accessing the archive.
To update an archive, PKZIPz creates a temporary file containing the original archive’s compressed data. When processing is complete, SecureZIP deletes the old archive and assigns its name to the temporary file.
The updated archive has allocation attributes from ARCH* commands or their defaults instead of the previous archive’s allocation.
Note: The temporary file(s) may require as large an allocation as the archive itself. Use the TEMP* commands to specify sufficient allocation.
If the archive came from another platform, the created data set must be created on MVS as sequential or as a PDS member with type U, F, or FB records. For best processing, generate this data set with a block size of at least 4000 bytes.
PKZIPz will create the archive with the <archive name>.
If this is to be a first member of a PDS, use ARCHIVE_DIR_BLOCKS to specify the allocation of directory blocks or use the default.
In PKUNZIP Processing The ARCHIVE_DSN command specifies the archive name to be read in or viewed by the PKUNZIP program.
Note: Either this command or the –ARCHIVE_INDD command must be used to identify an archive. There is no default.
–ARCHIVE_DSN(<archname>)
archname - This is the complete data set name of the ZIP archive.
156
PKZIPz will perform a SYSTEM ENQUE to lock out other users from using the archive.
–ARCHIVE_DSORG
Synonyms Include: –ARCHDSORG
For a new or updated ZIP archive, the data set organization is specified using the ARCHIVE_DSORG command. The command may specify one of four organizations with Sequential the default. Note, with the exception of VSAM files PKZIPz can determine the data set organization by the data set name in the ARCHIVE_DSN command.
–ARCHIVE_DSORG(PO|PE|PS|VS)
PO - Partitioned data set archive.
PE - Partitioned data set enhanced archive.
PS - Physical sequential archive.
VS - Virtual storage aaccess method archive.
Note: The program can determine the organization of the archive by the data set name, except for VSAM files.
–ARCHIVE_FASTSEEK
Synonyms Include:
Control fast archive directory seek logic for selected disk archive data set organizations.
ARCHIVE_FASTSEEK= Y|N
The central file directory for an archive is located at the back of the archive data set and local File directory entries are interspersed throughout the archive. When this setting is enabled with “Y”, PKZIP and PKUNZIP will use direct I/O techniques to locate the directory entries for view, extract and archive update processing.
In order to be effective, the archive data set must reside on disk as DSORG=PS (Physical Sequential) with RECFM=U or RECFM=FB. When STAGE_TAPE_ON_DISK=Y is specified, the fast seek logic will take effect for the temporary disk archive once it has been copied from tape.
If fast seek processing cannot be performed, message ZPAM561I is issued, and sequential processing of the archive directory entries is performed.
157
–ARCHIVE_INFILE
Synonyms Include: –ARCHINDD, –ARCHIFILE, –ARCHINFILE,–ARCHIVE_INDD, –ARCHIVE_IFILE
The ARCHIVE_INFILE command specifies a DD statement that describes a ZIP archive to be read in for processing. Use this command when the archive is not to be updated and the processed file is to be written to another destination using ARCHIVE_OUTFILE. Also use this command when processing tapes and GDG’s. Do not use this command with the ARCHIVE_DSN command.
–ARCHIVE_INFILE(<DDname>)
DDname - This is the DD statement in the JCL that identifies the ARCHIVE to be read.
The same <DDname> may not be used for ARCHIVE_OUTFILE.
–ARCHIVE_LRECL
Synonyms Include: –ARCHLRL
For a new or updated ZIP archive, the logical record length is specified using the ARCHIVE_LRECL command. If ARCHIVE_RECFM(U) is specified for sequential archives, a default record length of 0 is established. Otherwise the block size is used. Note that the command ARCHIVE_DATACLASS overrides this default.
–ARCHIVE_LRECL(<lreclength>)
lreclength - The logical record length for the new or updated ZIP archive.
–ARCHIVE_MGMTCLASS
Synonyms Include: –ARCHMCLASS
For new file allocation when doing PKUNZIP processing, these classes are passed to SMS when data set allocation occurs.
–ARCHIVE_MGMTCLASS(<SMS Management Class>)
See IBM’s DF/SMS manuals for further information about this parameter.
The following parameter option for SMS classes accommodates earlier PKZIP releases:
_NONE_
For example:
ARCHIVE_MGMTCLASS=_NONE_
158
An ACZDFLT parameter of _NONE_ maintains the behavior of earlier releases of PKZIP (pre-5.6) for SMS specifications.
–ARCHIVE_OUTFILE
Synonyms Include: –ARCHIVE_OUTDD, –ARCHIVE_OFILE, –ARCHOUTDD, –ARCHOFILE, –ARCHOUTFILE
The ARCHIVE_OUTFILE command specifies a DD statement that points to a ZIP archive to be written. Use this command when the input archive is not to be updated with new information. This command is mainly used when processing tapes and GDG’s. Do not use this command in conjunction with the ARCHIVE_DSN command.
–ARCHIVE_OUTFILE(<DDname>)
DDname - This is the DD statement in the JCL that identifies the ARCHIVE to write. It must not be the same as used for ARCHIVE_INFILE.
If the archive is updated, the JCL parameter DISP=MOD should not be used to extend the archive. DISP=OLD should be used instead to allow the archive to be overwritten.
If the archive is not updated, then the input archive will be copied to the <DDname> archive. The <DDname> attributes in the JCL are used to define the output archive. Any ARCH* commands are ignored.
In the event of an error occuring during ZIP processing such that the process does not complete, the output data set within the archive should not be used. The status of the data set is determined once the process completes and therefore will not be determined if an error is encountered.
–ARCHIVE_RECFM
Synonyms Include: –ARCHTYPE
For a new or updated ZIP archive, the record format may be specified using the ARCHIVE_RECFM command. The record specification may be one of four types with U (Undefined) as the default.
–ARCHIVE_RECFM(U|F|FB|FBS)
U - Undefined records (default) (note also that this default is ignored if an associated SMS command of ARCHIVE_DATACLASS is used).
F - Fixed records.
FB - Fixed-Block records.
FBS - Fixed-Block Standard records.
159
An undefined specification (U) causes any ARCHIVE_LRECL specifications to be ignored. Similarly, an unblocked file specification will cause ARCHIVE_BLKSIZE to be ignored.
–ARCHIVE_SPACE_MULTIVOL
Synonyms Include: N/A
The ARCHIVE_SPACE_MULTIVOL command controls whether the dynamic allocation of a new non-VSAM archive data set will request multiple volumes when ARCHIVE_DATACLASS is not in effect.
–ARCHIVE_SPACE_MULTIVOL=Y|N
N - When a value of “N” is specified, or an ARCHIVE_DATACLASS is specified, SecureZIP does not provide a volume count in the dynamic allocation request. When multiple volumes are required to hold the archive under this condition, the operating system may reject the volume extension with an associated IEC032I-04 E37 error.
Y - When “Y” is specified without an ARCHIVE_DATACLASS, a maximum of 59 volumes will be requested in the DYNALLOC request. When this option is enabled, the catalog will show the archive data set as being a multi-volume data set.
Message IGD17271I Allocation has been allowed to proceed for data set may appear in the JOB log from the system but will not affect PKZIP processing.
Note: See the SecureZIP for z/OS System Administrator’s Guide for more information on SMS dataclass considerations. See also the section “Large File Considerations” in Chapter 8 for discussions regarding SMS class controls of extended size data sets.
–ARCHIVE_SPACE_PRIMARY
Synonyms Include: –ARCHPRIMARY
For a new or updated ZIP archive, the number of allocation units in the primary extent is specified using the ARCHIVE_SPACE_PRIMARY command.
The default is not used if ARCHIVE_DATACLASS is specified.
–ARCHIVE_SPACE_PRIMARY(<allocation units>)
allocation units - This is an 8-character field specifying the number of allocation units for the primary extent of the new or updated ZIP archive.
00000010 - Ten (cylinders) is the default.
Allocation units are automatically released for a sequential archive.
160
–ARCHIVE_SPACE_RLSE
Synonyms Include: –ARCHIVE_RLSE, –ARCHIVE_RELEASE, –ARCHIVE_SPACE_RELEASE, –ARCHRLSE, –NOARCHRLSE, –ARCHNORLSE
This command specifies whether free space should be released when a ZIP archive is deallocated.
–ARCHIVE_SPACE_RLSE(Y|N)
Y - YES - The deallocated free space is released following compression. This is the default action taken for sequential data sets.
N - NO - The deallocated free space is not released following compression. This is the default action taken for partitioned data sets.
–ARCHIVE_SPACE_SECONDARY
Synonyms Include: –ARCHSECONDARY
For a new or updated ZIP archive, the number of allocation units in the secondary extent is specified using the ARCHIVE_SPACE_SECONDARY command. If specified, the data unit number must not be 0.
The default is not used if ARCHIVE_DATACLASS is specified.
allocation units - This is an 8-character field specifying the number of allocation units for the secondary extent of the new or updated ZIP archive.
00000010 - Ten (cylinders) is the default.
–ARCHIVE_SPACE_TYPE
Synonyms Include: –ARCHSPACE
For a new or updated ZIP archive, the type of allocation units may be specified using the ARCHIVE_SPACE_TYPE command. Note the default is not used when ARCHIVE_DATACLASS is specified.
–ARCHIVE_SPACE_TYPE(<TRK|CYL|BLK|MB|KB>)
TRK - (also TRKS and TRACKS) Allocation by tracks.
CYL - (also CYLS and CYLINDERS) Allocation by cylinders.
BLK - (also BLKS and BLOCKS) Allocation by blocks (Note that the block size is specified in the ARCHIVE_BLKSIZE command.
KB - (also KILOBYTES) Allocation by Kilobytes for a VSAM archive.
161
MB - (also MEGABYTES) Allocation by Megabytes for a VSAM archive.
VSAM Note: Both the primary and secondary extents are allocated at 100 allocation units unless changed by the –VSAM_SPACE_PRIMARY or the –VSAM_SPACE_SECONDARY commands.
This command specification can be overridden at the data level by the VSAM_DATA_SPACE_TYPE command. At the data level, the corresponding cluster information is not recognized.
–ARCHIVE_STORCLASS
Synonyms Include: –ARCHSCLASS
For a new or updated ZIP archive, the DF/SMS storage class may be specified using the ARCHIVE_STORCLASS command. If the command is not specified no storage class is used.
–ARCHIVE_STORCLASS(<storclass>)
storclass - The names of the DF/SMS storage class where the updated or new archive is to reside. There is an 8-character limit.
For new ZIP archives that are members of a PDS, the PKZIPz DF/SMS command should specify the PDS class and the non-DF/SMS command should specify the PDS volume or unit of the allocation.
–ARCHIVE_TIMESTAMP
Synonyms Include: –TIMESTAMP
This command specifies the source of the date and time for a compressed file. The default is the LOCAL time, as set on the system.
–ARCHIVE_TIMESTAMP(CREATE|CREATEGMT|CREATEUTC|GMT|LOCAL|UTC)
CREATE - Specifies the creation date of the MVS data set with time of 00:00:00. This is because standard MVS systems retain the data set’s creation date but do not retain the time of creation. If this creation date does not exist, the LOCAL time is used. Members of a PDS will have the timestamp associated with the data set, not with the individual members.
CREATEGMT - Specifies the creation date of the MVS data set with a time of 00:00:00 as in CREATE. Except if the creation date does not exist, the UTC option is used.
CREATEUTC - Specifies the creation date of the MVS data set with a time of 00:00:00 as in CREATE. Except if the creation date does not exist, the UTC option is used.
162
GMT - Specifies the Greenwich Mean Time as set on the system. Time zones are not specified here; therefore, it is the same time, world-wide. The time is captured at the time ZIP processing begins.
LOCAL - Specifies the LOCAL time as set with the system. The LOCAL time is based on the UTC time with any adjustments made for time zones.
UTC - Specifies the Greenwich Mean Time as set on the system. Time zones are not specified here; therefore, it is the same time, world-wide. The time is captured at the time ZIP processing begins.
The time captured for the archive is the point at which ZIP processing begins and is the same for all files of that archive.
–ARCHIVE_UNIT
Synonyms Include: –ARCHUNIT
For new or updated ZIP file allocation, the generic units for the archive can be specified using the ARCHIVE_UNIT command. The default, should a unit be required, is the installation default, typically SYSDA.
–ARCHIVE_UNIT(unitname|SYSDA)
unitname - An 8-character field specifying the name of the generic unit to which the archive is to be allocated.
SYSDA - The default specification.
For new ZIP archives that are members of a PDS, the PKZIPz DF/SMS command should specify the PDS class, and the non-DF/SMS command should specify the PDS volume or unit of the allocation.
–ARCHIVE_VOLUMES
Synonyms Include: –ARCHVOL
For a new or updated ZIP archive allocation, the volume(s) is specified using the ARCHIVE_VOLUMES command.
–ARCHIVE_VOLUMES(<volname>[ <volname> <volname>…])
volname - A 217-byte field specifying the name of the volume(s) onto which the new or updated ZIP archive is allocated. There may be up to 31 volume names specified with this command.
For an archive that is a new member of a new PDS, the first <volname> will only be used.
For a VSAM archive, the volumes are specified at the Cluster Level.
163
–ARCHIVE_ZIPFORMAT
Synonyms Include: –FULL_LBI, –XTAPE_LBI, GZIP
This parameter qualifies the ZIP archive format to be written based on compatibility and performance requirements. It also specifies whether Large Block Interface (LBI) processing should be used for LBI-eligible devices.
–ARCHIVE_ZIPFORMAT(FULL|FULL_LBI|GZIP|XTAPE|XTAPE_LBI)
FULL – The default format: A standard ZIP archive is written with non-LBI ARCHIVE_BLKSIZE specifications (32,760 or less).
FULL_LBI – For LBI-eligble devices: A standard ZIP archive is written with an LBI-compatible ARCHIVE_BLKSIZE (> 32,760).
GZIP – Perform GZIP-compatible processing.
XTAPE – For eligible tape cartridge devices: A high-performance format ZIP archive is written with non-LBI ARCHIVE_BLKSIZE specifications (32,760 or less).
XTAPE_LBI – For eligible tape cartridge devices: A high-performance format ZIP archive is written with an LBI-compatible ARCHIVE_BLKSIZE (> 32,760).
FORMAT Usage Restrictions
FULL Fully portable to other releases and platforms.
Can be transported to other devices and platforms using generic sequential data set read utilities.
164
FORMAT Usage Restrictions
FULL_LBI Fully portable archive format using large (LBI) block sizes to maximize device storage capabilities.
3480, 3490, 3590 devices
Conforms to IBM LBI processing requirements
ARCHIVE_RECFM=U only
Access requires an LBI-enabled release of PKZIP/SecureZIP
GZIP RFC 1951 & RFC1952 GZIP conformance to non-LBI devices
See the related chapter on “GZIP Processing”
XTAPE Provides high-performance single-stage archive write operations.
Provides subsequenct high-performance single-stage archive read operations.
3480, 3490, 3590 devices
Conforms to IBM LBI processing requirements
ARCHIVE_RECFM=U only
Read access, or Cross-device transport requires an XTAPE-enabled release of PKZIP/SecureZIP.
Archives in this format should only be transferred to other media by using PKZIP (or SecureZIP)
XTAPE_LBI XTAPE format using large (LBI) block sizes to maximize device storage capabilities.
3480, 3490, 3590 devices
Conforms to IBM LBI processing requirements
ARCHIVE_RECFM=U only
Read access, or Cross-device transport requires an XTAPE-enabled release of PKZIP/SecureZIP
Archives in this format should only be transferred to other media by using PKZIP (or SecureZIP)
Usage Notes
ARCHIVE_ZIPFORMAT(FULL) is automatically set for unsupported archive output devices when FULL_LBI, XTAPE or XTAPE_LBI is specified.
The Enhanced Tape Processing feature is required for both LBI and Extended Tape format processing.
The GZIP standard does not support PKWARE archive attributes; therefore, some SecureZIP features are not available for use when the GZIP format is enabled. Some features which are excluded from use are: strong encryption, digital signatures, multiple files per GZIP stream, self-extracting archives.
When enabled with GZIP, password-based 96-bit encryption is supported for decryption under PKZIP for MVS, PKZIP for zSeries, PKZIP for OS/400, PKZIP for i5/OS, SecureZIP for i5/OS, PKZIP for z/OS, and SecureZIP for z/OS.
When processing input GZIP archives, see also: GZIP_SUFFIX and GZIPCRC_IGNORE
XTAPE format archives written directly to tape by PKZIP/SecureZIP rely on the use of ZIP64 Data Descriptor record format. These ZIP file structures are documented in the ZIP File Format Specification (APPNOTE) published by PKWARE. Not all ZIP-compatible products include support for these formats, and you may experience problems reading
165
these archives if you need to process them for any reason outside of your zSeries environment.
XTAPE format archives use extended NOTE/POINT processing to achieve high-performance, one-stage tape processing for subsequent archive input processing. The NOTE information stored in the archive attributes is only valid when the archive remains on the volume to which it is written and is processed by an appropriate release of the software.
XTAPE and XTAPE_LBI archives contain device-dependent positioning information. Although the archive can be transferred to another media and successfully processed, it is strongly recommended that only a PKWARE product that supports XTAPE be used to transfer (using ACTION=COPY) the archive. Residual device-dependent positioning information will not be usable for high-speed access on other devices (or other cartridge file locations).
See ARCHIVE_BLKSIZE for information regarding LBI block size restrictions
XTAPE and LBI format archives may be accessed for VIEW processing by PKZIP/SecureZIP not licensed for Enhanced Tape Processing. (Older releases may require that the ARCHIVE_BLKSIZE be less than 32,760.)
Installations of PKZIP/SecureZIP that are not licensed for Enhanced Tape Processing can access XTAPE and LBI format archives for EXTRACT processing by using STAGE_TAPE_ON_DISK=Y.
An older release of PKZIP/SecureZIP attempting to access a tape archive written with an LBI block size (> 32,760) will receive an open error for the archive with an associated joblog message “IEC141I 013-E1,IFG0196L,jobname,stepname,ARCHIN”.
–ATTRIB_COMPATIBILITY
Synonyms Include: –ATTRCOMPAT, –ATTRIB_COMPAT, –ATTRIBUTE_COMPATIBILITY
This parameter governs the type of extended attributes that are stored in the archive. Both PKZIP for z/OS and SecureZIP for z/OS provide compatible attributes with PKZIP for MVS version 2.5 and above in the Systems/390 environment through the use of extended file information. New attributes may be built upon the Z390 attribute set in future releases.
–ATTRIB_COMPATIBILITY(Z390|MV25)
Although ZIP archives created by older releases of PKZIP for MVS can be processed by PKZIPz, extended attributes created by PKZIPz in Z390 mode are not compatible with executions of PKZIP for MVS version 2. For installations where multiple releases of the product are run with files being shared between systems, a mode of MV25 can be used so that the attributes created are acceptable to the older product versions.
166
–AUTHCHK
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
This command specifies that digital signature authentication processing should be performed. Separate authentication processing may be specified for either the archive central directory or files by using multiple commands. Optionally, specific signers may be specified to authenticate against.
-AUTHCHK(ARCHIVE|FILES,[certificate_store_type:selection][,R])
ARCHIVE|FILES - Designates the type of authentication that is to be performed. Either ARCHIVE or FILES can be specified on each command. Multiple AUTHCHK commands can be specified.
certificate_store_type:selection - An optional parameter used when attempting to validate that the associated signature(s) are from a specific source (via a public key identification). This sub-parameter designates the media containing the certificate(s) having the public key.
See SIGN_ARCHIVE for a discussion of the certificate store types and selection processing. Although a public-key X.509 certificate entity is to be used for authentication processing, a private-key entity can also be used to obtain the necessary public key.
It is possible that more than one certificate may be returned for a single common name or email search. If so, each is added to the list of validating sources.
When no specific certificates are requested, any signatories found in the archive are validated in accordance with the –{AUTHENTICATE} policy settings in effect.
[,R] - This is an optional flag indicating that certificate(s) specified in this AUTHCHK request must be satisfied for the run. This means that the public-key certificate information must be resolved on the local system and must pass validation as signatory for the type of AUTHCHK being performed. This parameter is not valid when a generic AUTHCHK(FILES) is requested.
All certificates specified with the “R” option must pass validation, or authentication will be marked as a failure. Only one authentication check command can be specified for the ARCHIVE type when a Required flag is set.
Processing Notes
AUTHCHK= is not honored from the defaults module (ACZDFLT or other user-designated module). A preferable technique is to use INCLUDE_CMD and reference an independent file from which the AUTCHK command(s) may be read (and file-protected from read access by the system’s security facility).
When FILE: is specified as the certificate lookup type, the data set name is treated in accordance with fopen() as documented in the IBM C/C++ Programming Guide. See “Performing OS I/O Operations - Using a Data Set Name”. Starting a filename with “//” indicates the file refers to a non-POSIX file or data set. The name specified is translated to upper case by the run-time environment.
167
A local certificate store configuration is required to complete the processing of this command. Even when a direct FILE specification is made to locate the private-key certificate, the {CSCA=} and {CSROOT=} certificate store components must be accessible to complete the certificate signing chain within the archive. This information is required to complete authentication processing on the target system when the local certificate store on that system does not contain the certificate authority chain required to validate TRUST.
Authentication will fail if none of the requested certificates can be accessed, regardless of the “R” required flag. If multiple requests are made and at least one signature is found, processing will continue normally.
When one or more non-required certificates are requested but none can be resolved in the local certificate store, generic authentication continues as if no specific requests had been made.
When one or more certificates (required or non-required) are requested, and any are found in the local certificate store, at least one certificate in the list must pass authentication. By providing a list of acceptable non-required certificates, any may pass validation to satisfy the authentication request. However, certificates specified for authentication with “R” must still pass validation.
An archive Directory authentication failure generates a minimum condition code of 6 (RC=6) for the execution unless an appropriate PKSUPPRC command is entered. This halts further processing for the archive except for ACTION=VIEW processing.
A file authentication failure generates a minimum condition code of 6 (RC=6) for the execution unless an appropriate PKSUPPRC command is entered. Processing continues for other files in the archive.
Signed files are tolerated by prior releases of PKZIP/SecureZIP for z/OS but are not processed for authentication.
Authenticity Check Policies Although the AUTHCHK command specifies which signature type (Archive or Files) should be checked, it does not specify the checks to be performed. (For an overview of authentication, see the section “Authentication” in Chapter 2). The policy configuration setting AUTHENTICATE= (which may also be entered as a command) specifies the checks to be performed when an AUTHCHK operation is processed.
–{AUTHENTICATE=[ALL]|[NOT]EXPIRED,[NOT]TRUSTED,[NOT] REVOKED,[NO]TAMPERCHECK}
The AUTHENTICATE policy setting is usually located in the local certificate store configuration file supplied by the SecureZIP administrator. If not present, AUTHENTICATE=ALL is the default. Use the negated form of a sub-parameter to exclude the test specified by that sub-parameter so that it is not performed.
Multiple AUTHENTICATE policy command sequences may be entered, but the sub-parameter values are not cumulative: only the last entry of AUTHENTICATE= encountered in the command stream takes effect.
168
ALL - This sub-parameter setting performs all authentication checks. If ALL is followed by negated sub-parameters, all checks are performed except for the ones in the negated sub-parameters. For example:
-{AUTHENTICATE=ALL,NOTEXPIRED}
performs all authentication checks except the test for expired certificates. With this setting, expired certificates will not cause an authentication error, but the TRUSTED and TAMPERCHECK tests must still succeed.
If “ALL” is not specified, only specified checks are performed. Any unspecified check is implicitly negated (set to the “NO/NOT” state) and is excluded.
For example: {…=NOTEXPIRED,NOTTRUSTED} checks only for TRUSTED. The EXPIRED test is explicitly excluded, and REVOKED and TAMPERCHECK tests are implicitly excluded. The setting {…=ALL,NOTEXPIRED,TRUSTED} explicitly excludes EXPIRED and TRUSTED such that only the tests for REVOKED and TAMPERCHECK are performed.
[NOT]EXPIRED - This sub-parameter performs certificate date-range validation on the certificates (including the certificate authority chain). Although the term “expired” is used, a certificate that has not yet reached its valid data range specification will also fail.
[NOT]REVOKED - This sub-parameter examines certificates and their trust chains to ensure that certificates have not been revoked by the certificate authority.
[NOT]TRUSTED - This sub-parameter signifies that the entire certificate authority chain must be validated. This includes locating the root (self-signed) certificate on the local system (as defined in {CSROOT=} within the local certificate store configuration).
[NO]TAMPERCHECK - This sub-parameter verifies the data stream against the digital signature.
–CALLMODE
Synonyms Include: N/A
This command is an internal use command that is used for environmental interfacing and should not be specified.
–CALLMODE(BATCH|ISPF|TSO)
Usage Notes
An echo of this internally generated command may appear in the run-time messages.
–CHECK_SYSIN_MEMBER
Synonyms Include: N/A
This is a defaults-module only parameter (since the value must be determined before the SYSIN command set is opened).
169
–CHECK_SYSIN_MEMBER(Y|N)
The default operation of PKZIPz is to verify that command input stored in a PDS or PDSE member exists. If the member is not found, then a message is issued and the PKZIP function is terminated.
"ZPCM010E MEMBER NOT ACCESSIBLE IN DATASET"
Installations that use very large PDS/PDSE libraries may want to avoid the overhead of searching the directory. Performance may be improved by specifying CHECK_SYSIN_MEMBER=N in the ACZDFLT module.
However, a system abend S013 will occur if the specified member does not exist in the library.
–COMPRESSION_LEVEL
Synonyms Include: –METHOD, –EN, –ES, –EX, –E0, –E1, –E2, –E3, –E4, –E5, –E6, –E7, –E8, –E9
This command specifies the speed and compression level when zipping a file.
–COMPRESSION_LEVEL(NORMAL|MAXIMUM|FAST|SUPERFAST|STORE|0|1|2| 3|4|5|6|7|8|9)
When updating files in a ZIP archive, COMPRESSION_LEVEL specifies a parameter that determines the compression level and speed to be used. The command specifies a level or degree of compression using a sliding scale of values. The related command, COMPRESSION_METHOD, specifies a compression algorithm.
The following table shows the compression levels available. Each strikes a different balance of compression level and speed of compression. The levels range from 0 (fastest speed with no compression) to 9 (highest level of compression, usually taking the longest amount of time and using the most processor time).
170
Synonym Level Usage
STORE, E0 0 No compression is performed.
SUPERFAST, E1 1 Compression Method: Deflate32 or Deflate64
FAST, E2 2 Compression Method: Deflate32 or Deflate64
NORMAL, E3 3 Compression Method: Deflate32 or Deflate64
MAXIMUM, E4 4 Compression Method: Deflate32 or Deflate64
E5 5 Compression Method: Deflate32 or Deflate64
E6 6 Compression Method: Deflate32 or Deflate64
E7 7 Compression Method: Deflate32 or Deflate64
E8 8 Compression Method: Deflate32 or Deflate64
E9 9 Compression Method: Deflate32 or Deflate64
Usage Notes
Compression levels 1 through 9 all work with Deflate32 and Deflate64 compression methods.
“Maximum” is retained at level 4 to provide equivalent compression ratios with earlier releases. Higher levels may yield better compression ratios than previously obtained with “Maximum”.
Compression results are data-stream dependent and produce non-linear results. When configuring a job for high volume processing, benchmarking results with sample file may be of value to find the best balance between compression ratio and resources (elapsed and processor time).
In many cases, levels 8 and 9 do not produce significant compression results over level 7.
When COMPRESSION_LEVEL=0, STORE, or E0 are specified, COMPRESSION_METHOD=STORE is set automatically.
When migrating from earlier releases of PKZIP or SecureZIP, a difference in compression ratio/processor time can be expected for a given data stream and setting. Although internal settings have been tuned to produce similar results across the scale of levels, a specific level setting may not produce faster speeds or better compression for a data stream. If these criteria are important, then benchmarking should be performed to achieve the “best fit” results with the new algorithms.
“METHOD” remains as a synonym for COMPRESSION_LEVEL to maintain command stream compatibility with earlier releases. However, it is recommended that the use of this command format be eliminated to remove ambiguity.
171
–COMPRESSION_METHOD
Synonyms Include: –DEFLATE32, –DEF32, –DEFLATE64, –DEF64, –STORE
This command specifies the compression algorithm to use when compressing a file during ZIP processing.
–COMPRESSION_METHOD(DEFLATE32|DEFLATE64|STORE)
See also the COMPRESSION_LEVEL command, which specifies a degree of compression.
STORE performs no compression of the data. Deflate64 (using the same level control) will usually produce better compression with less processor time than Deflate32.
Usage Notes
When COMPRESSION_METHOD=STORE is specified, COMPRESSION_LEVEL=STORE will is set automatically.
The GZIP specification only supports Deflate32. When –GZIP mode is encountered, PKZIP will automatically switch from Deflate64 or STORE to Deflate32. In addition, if COMPRESSION_LEVEL has a setting of STORE, the level is changed to SUPERFAST.
Not all vendors of ZIP-compatible programs provide support for Deflate64-compressed data, and their products may not be able to extract files compressed with this advanced compression algorithm. If the intended target systems support Deflate64, then it may be chosen for the best compression/speed performance.
Deflate32 is equivalent to the compression method used in releases prior to the implementation of COMPRESSION_METHOD and is functionally compatible (see the migration note under COMPRESSION_LEVEL regarding performance).
The DCB option TRTCH=COMP should not be used for a target archive destined for a tape cartridge device supporting compression when a non-STORE form of ZIP compression or encryption is specified.
–CRLF
Synonyms Include: –NOCRLF
- Cross Platform Compatible command (iSeries, OS/400, UNIX, and Windows).
This command determines whether special delimiters or terminators are inserted when a file is being extracted from a ZIP archive.
–CRLF(Y|N|C[,STRICT])
Y - YES - Insert CR (carriage control), LF (line feed), or CZ (Ctrl-Z), as appropriate.
N - NO - Do not insert CR, LF, or CZ.
C - COMPATIBILITY - Changes the way PKZIPz processes the last record in a file.
172
Y,STRICT - This special setting specifies that during UNZIP text-file processing, strict adherence to the DATA_DELIMITER and FILE_TERMINATOR character sequences is required to identify the end of a record. This combination may only be specified through command input and should be coded as “-CRLF(Y,STRICT)” as the last CRLF command encountered. Any other CRLF command will switch “STRICT” off.
When extracting a text file from a ZIP file that contains no internal delimiters or terminators of CR, LF, or CZ, you can use CRLF(N) so that the PKUNZIP program creates fixed record lengths for the output. The maximum record length of the extracted data set determines the output record length. The last record of the output is filled with EBCDIC spaces (Hex 40) if needed.
FILE_TERMINATOR() and DATA_DELIMITER() may be also be used and the PKUNZIP program will search for default delimiters.
See also DATA_TYPE(TEXT).
In PKZIP Processing CRLF=Y normally places the DATA_DELIMITER character(s) after every record (including the last one) before conditionally adding the FILE_TERMINATOR character(s).
CRLF=C specifies that the last record should not have the DATA_DELIMITER characters added after the last record of the file, and should only have the FILE_TERMINATOR character(s) added.
Note: –CRLF(Y,NOEOFDELIM) also performs this action.
If the default values for DATA_DELIMITER and FILE_TERMINATOR are taken, the same output results are seen with either CRLY=Y (standard) or CRLF=C. The advantage of using CRLF=C or CRLF(Y,NOEOFDELIM) is that finer control of the last control characters in the file can be achieved through the FILE_TERMINATOR specifications.
In PKUNZIP Processing CRLF=C during an EXTRACT causes additional line control interpretation to be done when the DATA_DELIMITER and FILE_TERMINATOR characters specified do not accurately match the source file. This is a compatibility option (PKZIP MVS 2.x) that sets the FILE_TERMINATOR to x’0D0A1A’ and treats this terminator as the last record’s delimiter.
Use of CRLF=C or CRLF=Y (without STRICT) may cause records to be split when binary data (within a text file) is found to contain any of the typical line control characters.
CRLF=Y causes any of the specified DATA_DELIMITER control characters to act as a record delimiter, regardless of sequence. X’1A’ (Ctrl-Z) is also considered to be a delimiter, even when not specified in the command set.
CRLF(Y,STRICT) may be used in conditions where a multi-character record delimiter (such as x'0D0A' from a PC) is being read but there are also spurious control characters intermixed with the data. Assuming that an inbound text file used x'0D0A' as the record delimiter with default processing, any x'0D' or x'0A' in the data stream would normally cause a record break during output operations. However, with STRICT turned on, only exact sequences of x'0D0A' would cause a record break, and the indivdual occurances or reversed x'0A0D' will be kept as part of the data stream for subsequent translation. Only the character streams specified in DATA_DELIMITER and FILE_TERMINATOR are used in the scan.
173
Note: When CRLF(Y,STRICT) is enabled, a check for an exact match of the FILE_TERMINATOR stream will be done before checking the DATA_DELIMITER characters. If there are no data bytes found since the preceeding record when a positive match of the terminator string occurs, no record is written. This will result in an empty output file when only the FILE_TERMINATOR stream is found in the extracted data. For example, if x'0D0A' are specified in both FILE_TERMINATOR and DATA_DELIMITER, a stand-alone x'0D0A' at the end of the uncompressed data stream will be treated as NULL information because it matches the FILE_TERMINATOR.
ACZDFLT (MCZDFLTS macro) When CRLF=C is used in the MCZDFLTS macro and FILE_TERMINATOR is not specified, the default for FILE_TERMINATOR will be set to CRLFCZ(x’0D0A1A) instead of the standard default of CZ(x’1A’). This yields equivalent ZIP results when CRLF=Y is specified with its defaults.
“–FILE_TERMINATOR=” can be specified along with –CRLF=C to ZIP a file, resulting in no control characters at the end of the file.
If both CRLF=C and FILE_TERMINATOR=CZ are specified, then FILE_TERMINATOR=0D0A1A is substituted. FILE_TERMINATOR=1A can be used to override this substitution.
Processing Examples
–DATA_DELIMITER CRLF = x'0A0D'
–FILE_TERMINATOR CZ = x'CZ'
CRLF(N) No control characters are inserted after any records.
No control characters are inserted at the end of the file.
Rec1_dataRec2_data…
CRLF(Y) All records are terminated with DATA_DELIMITER characters.
After the final record, the –FILE_TERMINATOR character is added.
Assuming the distribute defaults of: –DATA_DELIMITER=crlf –FILE_TERMINATOR=cz
Rec1_dataCRLF Rec2_dataCRLF Last_recordCRLF CZ
CRLF(C) All records except the last record are terminated with –DATA_DELIMITER characters.
After the final record, the –FILE_TERMINATOR character is added.
Assuming the distribute defaults of: –DATA_DELIMITER=crlf –FILE_TERMINATOR=cz
Rec1_dataCRLF Rec2_dataCRLF Last_record CZ
CRLF=Y,NOEOFDELIM All records except the last record are terminated with –DATA_DELIMITER characters.
After the final record, the –FILE_TERMINATOR character is added.
Same as CRLF(C).
174
–DATA_DELIMITER
Synonyms Include: –DELIM
- Cross Platform Compatible command (iSeries OS/400, UNIX, and Windows).
In PKZIP Processing: When compressing a file as text (not binary), the DATA_DELIMITER command specifies what character(s) to store at the end of each record to differentiate records. (See the CRLF and FILE_TERMINATOR commands regarding control over the last record). When compressing a file as binary, the DATA_DELIMITER command is ignored.
–DATA_DELIMITER(<delim chars>)
Delim chars - The delimiter characters to be appended. There may be 0-4 characters specified in any combination:
CR - Appends an ASCII Carriage Return (hex 0D).
CZ - Appends an ASCII Ctrl-Z character (hex 1A).
LF - Appends an ASCII Line Feed character (hex 0A).
() - No delimiters at all.
The default is CRLF if no DATA_DELIMITER command is specified.
Note: Transfers of Microsoft- Disk Operating System (MS-DOS) records use a CRLF for a delimiter, while UNIX records use a LF. See –INCLUDE_CMD=TOMSDOS|TOUNIX for more information about target platform requirements.
When extracting the file(s), the same DATA_DELIMITER command should be used to differentiate each record, just as it was when it was compressed.
PKZIPz searches for one each of CR, CZ, and LF characters as a default for text file record delimiters. If a file was compressed with double characters as delimiters—for example, DATA_DELIMITER(LFCZLF)—and the file is later decompressed without the DATA_DELIMITER command (a default search is used), PKZIPz uses each LF as a record delimiter. It then creates extra record(s) to accommodate for the duplicate characters—for example, LF.
In PKUNZIP Processing When decompressing a text file (not binary), the DATA_DELIMITER command specifies what characters to look for at the end of records (except the last) that serve as delimiters. The delimiter is removed from the record when it is decompressed. The last record of the file ends with the characters specified in the FILE_TERMINATOR command. When decompressing a binary file, the DATA_DELIMITER command is ignored.
–DATA_DELIMITER(<delim chars>)
delim chars - The delimiter characters to be appended. There may be 0-4 characters specified in any combination:
175
CR - Appends an ASCII Carriage Return (hex 0D).
CZ - Appends an ASCII Ctrl-Z character (hex 1A).
LF - Appends an ASCII Line Feed character (hex 0A).
() - No delimiters at all.
The default is CRLF if no DATA_DELIMITER command is specified.
Default processing of records. PKZIPz will search for a range of delimiters when the DATA_DELIMITER command is not used. They are: CRLFCZ, LFCRCZ, CRLF, LFCR, CRCZ, LFCZ, CR, and LF. This default may be used unless special delimiter combinations were assigned during compression. To assure correct location of records, the same DATA_DELIMITER command used in compression should be used to decompress as well.
–DATA_STORAGE
Synonyms Include: –CACHEMEMORY
Cache memory may be specified, with the DATA_STORAGE command, in order to increase processing speed. This command specifies the total number of bytes to be allocated for caching.
-DATA_STORAGE(<bytes>|<nK>|<nM>|MAX)
bytes - Specifies the total number of bytes assigned for caches in PKZIPz, where <bytes> may range from 64000 to the maximum region size.
The unit may be specified in bytes, K (kilobytes), or M (megabytes) with no commas. To specify a cache memory of 3 megabytes, specify DATA_STORAGE=3M.
MAX - Specifies that PKZIP should allocate the maximum amount of the REGION to hold ZIP processing data.
A larger file may be processed in less time by specifying a larger cache memory. A larger cache memory increases virtual memory for compression operations that may decrease the necessary number of disk accesses. This reduces I/O time and thus improves compression performance time.
Warning: Be sure not to exceed your system’s capacity when specifying very large amounts of cache memory—for example, of 1 gigabyte (DATA_STORAGE=1024M). Claiming too large a cache memory in combination with a very large region size (such as REGION=0M) without sufficient underlying storage and/or page data sets can create serious problems. It is suggested that you confirm in advance with the proper systems management personnel that such large settings will work.
PKZIPz can use multiple caches during processing which can vary the actual amount of virtual memory that is used. The amount is affected by the number and size of the files being processed. In addition, the actual value used for monitoring may be dynamically adjusted to meet processing requirements.
176
Usage Notes
When MAX is specified, a portion of the REGION is automatically reserved for programs, work buffers and processing control information. However, in some cases, the general purpose settings may be insufficient to permit virtual storage to hold high volumes of file control information (such as thousands of PDS members with their respective directory information) as well as a high volume of ZIP data from the currently active file. See the following note regarding virtual storage constraint relief.
When virtual storage shortages become evident during processing (S878 or S80A abends), the problem may be alleviated by decreasing the value for DATA_STORAGE, increasing the REGION size, decreasing MULTI_THREAD_LIMIT, or a combination of all three.
ARCHIVE_FORMAT=FULL|FULL_LBI require that files being processed for ZIP (add, freshen or update) have their resulting ZIP data held in a temporary location before being written to the archive. The ZIP data is normally buffered within the job’s virtual storage. However, when there is insufficient virtual storage available (as governed through DATA_STORAGE), the ZIP data is staged to a temporary disk data set (ref. TEMPFILE TEMP_SPACE settings). Having sufficient virtual storage available will eliminate the need to write, and subsequently read back the ZIP data before writing it to the archive.
When adding or updating many files into an archive with MULTI_THREAD_LIMIT set higher than 1, all files concurrently being processed compete for the total cache memory available. Properly coordinating MULTI_THREAD_LIMIT, DATA_STORAGE and the job step REGION size will eliminate unnecessary TEMPFILE ZIP data staging.
ARCHIVE_FORMAT=XTAPE|XTAPE_LBI has less of a requirement for holding ZIP processing data in virtual storage for larger files than FULL or FULL_LBI. In addition, the use of tape for output archives introduces the possibility of waiting for secondary tape mounts. These waits can cause compressed/encrypted ZIP data to accumulate rapidly within the region while awaiting operational intervention on the tape unit. For this reason, MAX will be set to a lower value (such as 4M) to avoid stressing the paging subsystem. However, a specific higher value may be set to permit additional processing of data while the tape mount is satisfied.
–DATA_TRANS_API_ERRLIM
Synonyms Include: N/A
This setting currently has no effect.
–DATA_TRANS_API_ERRLIM(<threshold #>)
threshold # – Default 0
177
–DATA_TRANS_API_ERROR
Synonyms Include: N/A
Identify the type of processing to occur when an API error occurs.
–DATA_TRANS_API_ERROR(STOPRUN|ABEND|IGNORE>)
STOPRUN traps any program exception, displays the results of the trap, and causes the end of the SecureZIP execution.
ABEND causes the API to allow an abend of the user API withour trapping the program exception, allows a dump to occur, and ends the SecureZIP execution.
IGNORE traps any program exception, displays the results of the trap, and continues with the next record or file.
–DATA_TRANS_API_LANGUAGE
Synonyms Include: N/A
The language used to code the API. Basic Assembler Language (ASM) is the default.
–DATA_TRANS_API_LANGUAGE(ASM|COBOL)
–DATA_TRANS_API_NAME
Synonyms Include: N/A
The name of the data record transformation API load module. Place this load module into a JOBLIB, STEPLIB or a system linklist library.
–DATA_TRANS_API_NAME(<module name>)
module name – Up to 8 character name of the load module to be used as the data record transformation API.
Note: Use of the NOAPI control card negates all USER API processing. Any information placed into the DATA_TRANS_API control cards is ignored.
–DATA_TRANS_API_PARM
Synonyms Include: N/A
This control card can be used to pass information to the User API.
178
–DATA_TRANS_API_PARM(<user data>)
user data – Default blanks, can be up to 80 bytes
–DATA_TRANS_API_TRACE
Synonyms Include: N/A
This allows headings, control blocks, registers, and data areas to be presented in SYSPRINT to help in the debugging of a User API.
–DATA_TRANS_API_TRACE(0|1|2|3|4)
0 = Trace Off
1 = Basic
2 = Medium
3 = Low Level
4 = Very Low Level
The higher the number, the more volume of output.
–DATA_TRANS_API_WORKSIZE
Synonyms Include: N/A
The size of the work area to be used for the API. This area can be used to pass information between instances of the API being called and will be retained for the life of the run.
–DATA_TRANS_API_WORKSIZE(<work size in bytes>)
work size – Default 4096 max is 32768
–DATA_TYPE
Synonyms Include: –DETECT, –BINARY, –TEXT, –DETECTX
This command specifies that files for compression are either binary, text, or detectable. If the modifier is (BINARY), no translation is performed on the files. If the modifier is (TEXT), text files are files selected for compression and are translated from EBCDIC to ASCII before compression. If neither of these is specified, the program makes a determination (DETECT) based on the existing data type. The program reads in a portion of the data, evaluates it, and determines the appropriate process.
179
–DATA_TYPE(DETECT|BINARY|TEXT|DETECTX)
If you know the file type, you can save processing time by specifying DATA_TYPE(BINARY), DATA_TYPE(TEXT), or DATA_TYPE(BINARY) with SAVE_LRECL(Y).
In PKZIP Processing
When specifying –DATA_TYPE(BINARY):
No translation of the data is performed, and record terminators are not inserted. A binary file contains no delimiters between records and should only be used when the target system (for UNZIP) will be able to handle the EBCDIC format. Variable length files should be processed with the addition of the SAVE_LRECL(Y) command. This command is commonly used when exchanging files between Systems/390 operating environments, for example, load modules.
When specifying –DATA_TYPE(TEXT):
A compressed text file is stored as ASCII (unless otherwise specified with TRANSLATE_TABLE_DATA) and is stored with the specified delimiters (DATA_DELIMITER) and terminator (FILE_TERMINATOR). Note that the translation defaults and delimiter and terminator defaults of a stored text file from PKZIPz make the file compatible with compressed files on other platforms. This enables compressed text files to be extracted onto other platforms.
When specifying –DATA_TYPE(DETECT) or –DATA_TYPE(DETECTX) :
PKZIP attempts to dynamically determine whether the data should be translated into TEXT format. A portion of the file (see DATATYPE_DETECT_DEPTH) is examined using the tailorable DETECTXT translation table (see DATATYPE_DETECT_TABLE ) and is compared to the value specified in DATATYPE_TEXT_PERCENT.
In PKUNZIP Processing:
When specifying –DATA_TYPE(BINARY):
If the raw format of the data is desired, regardless of whether the originating system ZIPPED the file as TEXT, use this command.
Binary processing does not attempt to resolve record delimiters. As a result, the data is streamed into records according to the file allocation specifications. Note that when using PKZIPz to create binary files that are targetted for another MVS system, SAVE_LRECL(Y) can be specified to preserve record lengths.
When specifying –DATA_TYPE(TEXT):
The selected file is treated as a text file regardless of the archive directory indicator for the file. This can be used when the originating system is known to have ZIPPED an ASCII text file as binary. To discover what file type exists in the archive directory entry, see the ACTION(VIEW) command.
When the PKUNZIP program extracts the selected file, it first translates the character set and then extracts records to the output file as determined by embedded record delimiters. (See
180
DATA_DELIMITER command). The delimiters are not included in the extracted file. If the output file is a fixed record length, then records that exceed the record length will be truncated and records that are smaller than the record length will be filled with EBCDIC spaces (hex 40).
If no delimiters are embedded in the selected file, the command CRLF(N) should also be used. This command directs the PKUNZIP program to not seek out record delimiters but instead use the maximum record size in creating the output.
When specifying –DATA_TYPE(DETECT):
The PKZIP archive layout contains an indicator that reflects whether the file was ZIPPED as text. PKZIPz honors that flag when DETECT is specified. This is the default setting. However, there are cases that DETECTX is recommended when TEXT data has been ZIPPED in an ASCII environment with a binary indication, for example, a workstation ZIP compatible product is used to create the archive.
When specifying –DATA_TYPE(DETECTX) :
On some platforms, for example, workstations, some ZIP utilities do not set the TEXT indicator although the data was ASCII text. In this situation, DETECTX is recommended so that PKZIPz attempts to dynamically determine whether the data should be translated into EBCDIC TEXT format. A portion of the file (see DATATYPE_DETECT_DEPTH) is examined using the tailorable DETECTXT translation table (see DATATYPE_DETECT_TABLE ) and compared to the value specified in DATATYPE_TEXT_PERCENT. (Note that the detection depth is limited in size to the first internal buffer being extracted. This is typically less than 64K).
–DATATYPE_DETECT_DEPTH
Synonyms Include: –DATATYPE_SCAN_DEPTH, –DETECT_DEPTH
This command specifies the distance that a file is scanned before making a determination as to whether it is binary or text. It can be specified as a number of records (1000R) or as a size in bytes (64000), Kilobytes (64K), or Megabytes (4M).
–DATATYPE_DETECT_DEPTH(<amt>)
amt
amount in records (1000R).
amount in bytes (64000).
amount in kilobytes (64K) (8K is the default).
amount in megabytes (4M).
It is important to note that the amount of data specified in this parameter is buffered in virtual storage during the text/binary translation period and before the data is directed to the compression algorithms. (Compression cannot be performed until data translation and record delimiter processing is done, which follows DATA_TYPE detection). The buffering is done for performance reasons (to avoid Close/Open/Re-read overhead). However, sufficient virtual
181
storage (31-bit region) must be available to temporarily hold the specified quantity, or storage capacity issues may arise.
Note that in UNZIP processing with DETECTX, record count is changed to a maximum setting of 64K. Since the data is being scanned for ASCII characters before record processing is determined, a record count is not applicable. The amount of data scanned for DETECTX is also limited to the amount of data returned by the decompression engine (typically a maximum of 64K) and is dynamically rounded down as needed.
–DATATYPE_DETECT_TABLE
Synonyms Include: N/A
This command specifies the table of characters used to assess whether a byte is text or binary. The default table name is DETECTXT.
–DATATYPE_DETECT_TABLE(<tablename>|DETECTXT)
tablename - A tablename of characters used to assess whether a byte is text or binary.
DETECTXT - The default table as shipped with the product.
The specified TRANSLATE and TEST table is used to detect binary data within data records when DATA_TYPE(DETECT) is specified for ZIP processing.
The table is used as a character lookup table for each byte scanned through DATATYPE_SCAN_DEPTH. The binary value of each data byte is used to locate a position in the table. If the table position is x'00', then that byte is considered to be BINARY. If the table position is NONZERO, then the byte is counted as TEXT. The actual value in the table is not important, but the locations have been filled in with the equivalent offset for ease of editing (the comments reflect the character value where possible, although some bytes (such as CR/LF) are simply indicated with a comment of ".").
This table may be changed, copied, and re-assembled to adjust for data dependencies. The table used (loaded as a load module) is specified in DATATYPE_DETECT_TABLE and may be specified either in the defaults module or by command (Seemembers in INSTLIB(ASMDETXT) and (DETECTXT).
–DATATYPE_TEXT_PERCENT
Synonyms Include: N/A
This command specifies the percentage of the sample that must meet the “text” criteria before it will be considered to be TEXT.
–DATATYPE_TEXT_PERCENT(<percent>)
percent - This is the percentage from 1-100 that is required (97% is the default).
182
If the entire file is read before DATATYPE_DETECT_DEPTH is reached, then the percentage is computed according to the number of bytes read. For example, if DATATYPE_TEXT_PERCENT=97 is specified, with DATATYPE_DETECT_DEPTH=64K, then .03 * (64*1024) = 1966 (rounded down). Once 1967 binary characters are found, then the entire DEPTH cannot meet 97% text, so the scan is terminated and the file is marked as BINARY.
Given the percentage listed above (97%), a file having 100 records, each containing 80 bytes of text with 2 bytes of additional termination information (total 82 bytes), passes as TEXT. 100 * 82 (8200) * .03 = 246 Thus, 246 bytes of binary data would be required to mark this file as BINARY, but there are only 200.
DDNAME_PARMLIB
Synonyms Include: N/A
This setting specifies the name of the JCL DD statement used to read the preset commands which are read before the //SYSIN member.
DDNAME_PARMLIB(<ddname>)
This setting is specified in the defaults module only.
ddname - This is the DDname of the preset parameters member.
PARMLIB - This is the default DDname.
–DDNAME_SYSIN
Synonyms Include: N/A
This command specifies the name of the JCL DD statement used to identify the SYSIN member. It may be specified in the defaults module or as an included PARMLIB command.
–DDNAME_SYSIN(<ddname>)
ddname - This is the DDname of the SYSIN member.
SYSIN - This is the default DDname.
–DDNAME_SYSPRINT
Synonyms Include: N/A
This command specifies the name of the JCL DD statement used to identify where messages will be written.
183
–DDNAME_SYSPRINT=<ddname>
ddname - This is the DDname for SYSPRINT output.
SYSPRINT - This is the default DDname.
This setting can be entered through a defaults module (see ACZDFLT), or as an EXEC PARM.
–DDNAME_ZPSORTIN
Synonyms Include: N/A
This command specifies the name of the JCL DD statement used for sorting directory information associated with VIEW processing. This should not need to be changed unless the name conflicts with other JCL allocation used in the same job step.
–DDNAME_ZPSORTIN(<ddname>)
ddname - The DDname to use for SORTIN.
ZPSRTIN - The default DDname.
Note: The value specified for –TEMP_UNIT is used to allocate a temporary work file with this DD.
–DDNAME_ZPSORTOUT
Synonyms Include:
This command specifies the name of the JCL DD statement used for sorting directory information associated with ACTION(VIEW) processing. This should not need to be changed unless the name conflicts with other JCL allocation used in the same job step.
–DDNAME_ZPSORTOUT(<ddname>)
ddname - The DDname to use for SORTOUT.
ZPSRTOUT - The default DDname.
–ECHO
Synonyms Include: –NOECHO
Commands used for the PKZIP and PKUNZIP programs are put into the output message data set when ECHO(Y) is specified. This is the default setting.
184
–ECHO(Y|N)
Y - YES - Log all output messages to SYSOUT.
N - NO - Do not log output messages to SYSOUT.
One would use ECHO(Y) if the ECHO(N) command had previously been used (either in the configuration module or through the JCL) to suppress output messages. Then the commands that are output begin with the ECHO(Y) command itself. Since the ECHO command is processed before it is activated, errors in this line would not appear in the output message data set.
–ENCRYPT_CERT_LIMIT
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
ENCRYPT_CERT_LIMIT(0|1-3275)
This command assists in restricting the number of certificates being used to represent a user or organization for each encrypted file. The limit number can be used to avoid long LDAP searches for generic search criteria that could consume virtual storage and processing resources. In addition, it can be used to allow processing to continue even if the limit is reached.
When the LDAP search requests are found to exceed a specified non-zero value, ZIP processing will continue with the number of certificates found.
When zero (0) is specified, then the default maximum value of 3275 is used. Under this condition, if the maximum limit is reached, ZIP processing will terminate.
–ENCRYPTION_METHOD
Synonyms Include: -STANDARD | AES128 | AES192 | AES256| BSAFE_AES128| BSAFE_AES192| BSAFE_AES256| BSAFE_DES| BSAFE_3DES| BSAFE_RC4
- Cross Platform Compatible feature (iSeries, OS/400, UNIX, and Windows).
185
Requires SecureZIP
When a ZIP action is requested to save a file in an archive and a password and/or recipient is provided, SecureZIP for z/OS will use an encryption method to protect the data. This command value specifies the processing method to employ.
Note: The value specified in the ENCRYTION_METHOD command represents a composite of cryptographic attributes, including encrytion algorithm, key length, and settings for cipher block chaining and block padding. The named value represents a schema of compatibility rather than the specific FACILITY being used.
Standard - This algorithm is the original algorithm used in PKZIP 2.x products and is compatible with other PKZIP 2.04g products that support standard encryption. This is the default value for password-only encryption unless the installation defaults module has been tailored differently.
AES128 - see BSAFE_AES128.
AES192 - see BSAFE_AES192.
AES256 - see BSAFE_AES256.
BSAFE_AES128 - A SecureZIP implementation of the AES 128-bit key algorithm, including cipher-block-chaining and block padding. When recipient-based encryption is requested, this is the default encryption method unless the installation defaults module has been tailored differently.
BSAFE_AES192 - A SecureZIP implementation of the AES 192-bit key algorithm, including cipher-block-chaining and block padding.
BSAFE_AES256 - A SecureZIP implementation of the AES 256-bit key algorithm, including cipher-block-chaining and block padding.
BSAFE_DES - A SecureZIP implementation of the DES 56-bit key algorithm, including cipher-block-chaining and block padding.
BSAFE_3DES - A SecureZIP implementation of the 3DES 168-bit key algorithm, including cipher-block-chaining and block padding.
BSAFE_RC4 - A SecureZIP implementation of the RC4 128-bit key stream algorithm.
Usage Notes
SECUNZIP/PKUNZIP will automatically detect which encryption method was specified during the ZIP process and operate accordingly.
During a SECZIP (ZIP) run, only 1 encryption method may be specified, and that method will be used for each file operated on.
By executing SECZIP at different times, various files within the archive may be saved with differing levels (and types) of protection. That is, some files may not be protected at all, while others may have different methods and/or passwords.
A “+” is shown in a View to indicate Standard Encryption protection is used for a file.
A “!” is shown in a View to indicate Strong Encryption protection is used for a file.
186
When specifying long passwords (requiring multiple control records) do not use the “+” continuation character (because it supplies an implicit blank in the command stream).
This enhanced feature for ADD, UPDATE, and FRESHEN applies to standard ZIP archives and not GZIP.
See the FACILITY_ENCRYPTDATA command for information on selecting a cryptographic service for the desired method.
The DCB option TRTCH=COMP should not be used for a target archive destined for a tape cartridge device supporting compression when a non-STORE form of ZIP compression or encryption is specified.
–EXCLUDE(dsname mask)
Synonyms Include: N/A
This parameter has no equivalent. It is a new command.
When selecting a large number of files via a mask selection it may be useful to eliminate some of the files from being processed, for example, GDGs, ZIP archives, or other special files that can be identified by their data set naming conventions.
See also: –SELECT_TAPE, –SELECT_VSAM, –SELECT_CATALOGED_ALIAS, and –RECALL_TO_ZIP for other selection-restricting capabilities.
The dsname mask may be a fully qualified file name or a masked name (similar to data set selection names) of 1 to 80 characters. (Embedded blanks in an MVS dsname for ZIP processing will truncate the mask.)
Multiple EXCLUDE commands may be specified in an execution. A table is built from all of the commands found and is scanned for a match against a candidate file for selection. The file will be excluded if ANY of the masks is a match.
Note that there is no default for this command, nor can one be specified in the ACZDFLT module. This is a run-time only command, although it may be specified through the PARMLIB DD or EXEC parms (including a parm string from a calling program) in addition to SYSIN.
Example:
Assume that PDS SYS1.PARMLIB contains members CLOCK01, CLOCK02, CLOCK11, and CLOCK13. If the following commands were issued for SECZIP:
SYS1.PARMLIB(CLOCK*) –EXCLUDE=SYS1.PARMLIB(*11)
Member CLOCK11 would be excluded from the ZIP process, while the other members would be processed.
187
–EXTRACT_PREVIEW
Synonyms Include: –PREVIEW
When the contents of a large archived file is unknown, it may be useful to extract a small portion of the file for the purpose of previewing the data. The EXTRACT_PREVIEW(nnnnnnnn) command limits the number of records to extract and can save a considerable amout of time in assessing data content.
–EXTRACT_PREVIEW(<nnnnnnnn>)
The parameter value specifies the maximum number of records to extract. If the value is either 0 (or not supplied) then the entire file is extracted.
–FACILITY_ENCRYPTDATA
Synonyms Include: none
Requires SecureZIP Enterprise Edition
-FACILITY_ENCRYPTDATA(IBMHARDWARE,IBMSOFTWARE,SECUREZIP)
When an ENCRYPTION_METHOD is used to protect the data, a choice of cryptographic facility (service) may be available to accomplish the requested encryption/decryption process. The values specify, in order of preference, facility types that SecureZIP should attempt to use to apply the algorithm associated with the specified ENCRYPTION_METHOD.
Only those facility types listed will be considered viable for use by SecureZIP to process the selected ENCRYPTION_METHOD. If a restricted list of facilities is designated, care must be taken in choosing a supported combination of method and facility.
IBMHARDWARE – If available on the system for the requested method, ICSF Cryptographic Services will be engaged to use hardware-accelerated cryptography.
IBMSOFTWARE – If available on the system for the requested method, ICSF Cryptographic Services will be engaged to use IBM-provided software cryptography.
SECUREZIP – SecureZIP software implementations will be engaged to support the specified method. All methods are supported by this facility type.
Supported Preference List Specifications
IBMHARDWARE
Only use ICSF APIs associated with IBM hardware acceleration. This will cause encryption methods not supported on the system via hardware to fail.
IBMHARDWARE,IBMSOFTWARE
188
Only use ICSF APIs, selecting Hardware when available, or ICSF software emulation otherwise. This will cause encryption methods not supported by ICSF to fail.
IBMHARDWARE,IBMSOFTWARE,SECUREZIP
This will conditionally select IBM ICSF hardware acceleration or ICSF software emulation and use SECUREZIP software facilities as a backup to ensure successful processing for the chosen method. This is the default setting.
SECUREZIP
Only use cryptographic routines provided by SecureZIP. No attempt will be made to select ICSF APIs.
Facility/Method Compatibility
The following table shows currently supported combinations. See the SecureZIP for z/OS System Administrator’s Guide for more information.
Method: IBMHARWARE IBMSOFTWARE SECUREZIP
Standard (PKWARE 96) Not Available Not Available PKWARE
AES128 ICSF(z9-109 only) ICSF(sys-dependent) RSA BSAFE Crypto-C
AES192 Not Available ICSF(sys-dependent) RSA BSAFE Crypto-C
AES256 Not Available ICSF(sys-dependent) RSA BSAFE Crypto-C
DES (56) ICSF(sys-dependent) ICSF(sys-dependent) RSA BSAFE Crypto-C
3DES (168) ICSF(sys-dependent) ICSF(sys-dependent) RSA BSAFE Crypto-C
RC4 Not Available Not Available RSA BSAFE Crypto-C
Usage Notes
The value(s) for this command setting can be specified in the defaults module.
The last command setting for FACILITY_ENCRYPTDATA takes precedence.
Exclusive use of IBM ICSF cryptographic services can be designated by eliminating “SECUREZIP” as a value from the list. However, if the designated ENCRYPTION_METHOD is not actively supported in the operating environment, the ZIP/UNZIP request is rejected.
Because SECUREZIP supports all methods, placing it before other facility types in the list effectively negates succeeding values.
To guarantee cross-platform compatibility, portions of encryption method processing may be performed by SecureZIP even when IBMHARDWARE or IBMSOFTWARE are chosen. However, at a minimum, the algorithm portion of the method will be satisfied by the selected operating facility type.
Additional information regarding cryptographic facility availability and selection may be found in the SecureZIP Administrator’s Guide under “SecureZIP ICSF Operations” and “Cryptographic Facility Utility.”
189
–FACILITY_HASH
Synonyms Include: none
Requires SecureZIP Enterprise Edition
-FACILITY_HASH(IBMHARDWARE,IBMSOFTWARE,SECUREZIP)
When a digital signature is created or authenticated, a choice of cryptographic facility (service) may be available to accomplish the data hashing portion of the process that generates the message-digest. The values specify, in order of preference, a list of facility types that SecureZIP should attempt to use for the hash operation.
Only those facility types listed will be considered viable for use by SecureZIP to process the selected ENCRYPTION_METHOD. If a restricted list of facilities is designated, take care to choose a supported combination of method and facility.
IBMHARDWARE – If available for use on the system for the requested method, ICSF Cryptographic Services will be engaged to use hardware-accelerated hash.
IBMSOFTWARE – If available for use on the system for the requested method, ICSF Cryptographic Services will be engaged to use IBM-provided software hash.
SECUREZIP – SecureZIP software implementations will be engaged to support the specified method. All methods are supported by this facility type.
Supported Preference List Specifications
IBMHARDWARE
Only use ICSF APIs associated with IBM hardware acceleration. This will cause hash methods not supported on the system by hardware to fail.
IBMHARDWARE,IBMSOFTWARE
Only use ICSF APIs, selecting hardware when available, or ICSF software emulation otherwise. This will cause hash methods not supported by ICSF to fail.
IBMHARDWARE,IBMSOFTWARE,SECUREZIP
This will conditionally select IBM ICSF hardware acceleration or ICSF software emulation, and use SECUREZIP software facilities as a backup to ensure successful processing for the chosen method. This is the default setting.
SECUREZIP
Only use cryptographic routines provided by SecureZIP. No attempt will be made to select ICSF APIs.
Facility/Method Compatibility
The following table shows currently supported combinations. See the SecureZIP for z/OS System Administrator’s Guide for more information.
190
Method: IBMHARWARE IBMSOFTWARE SECUREZIP
MD5 Not Available ICSF(sys-dependent) RSA BSAFE Crypto-C
SHA-1 ICSF(sys-dependent) ICSF(sys-dependent) RSA BSAFE Crypto-C
Usage Notes
The value(s) for this command setting can be specified in the defaults module.
The last command setting for FACILITY_HASH takes precedence.
Exclusive use of IBM ICSF cryptographic services may be designated by eliminating “SECUREZIP” as a value from the list. However, if the designated SIGN_HASHALG is not actively supported in the operating environment, the ZIP/UNZIP request will be rejected.
Because SECUREZIP supports all methods, placing it before other facility types in the list will effectively negate succeeding values.
Additional information regarding cryptographic facility availability and selection may be found in the SecureZIP Administrator’s Guide under “SecureZIP ICSF Operations” and “Cryptographic Facility Utility.”
–FACILITY_RANDOM
Synonyms Include: none
Requires SecureZIP Enterprise Edition
-FACILITY_RANDOM(IBMHARDWARE,IBMSOFTWARE,SECUREZIP)
When an ENCRYPTION_METHOD is used to protect the data, a choice of cryptographic facility (service) may be available to accomplish the requested encryption/decryption process. The values specify, in order of preference, a list of facility types that SecureZIP should attempt to use in generating random data associated with the requested method.
Only those facility types listed will be considered viable for use by SecureZIP to process the selected ENCRYPTION_METHOD. If a restricted list of facilities is designated, take care to choose a supported combination of method and facility.
IBMHARDWARE – If available on the system for the requested method, ICSF Cryptographic Services will be engaged to use hardware-based pseudo-random data generation.
IBMSOFTWARE – The IBMSOFTWARE value is permitted for syntax compatibility with other FACILITY statements. No ICSF APIs are currently identified for software-based pseudo-random data generation.
191
SECUREZIP – SecureZIP software implementations will be engaged to support the specified method. All methods are supported by this facility type.
Supported Preference List Specifications
IBMHARDWARE
Only use ICSF APIs associated with IBM hardware acceleration. This will cause random data generation associated with data encryption not supported on the system by hardware to fail.
IBMHARDWARE,IBMSOFTWARE
Same as IBMHARDWARE (because there are no identified ICSF software API facilities)
IBMHARDWARE,IBMSOFTWARE,SECUREZIP
This will conditionally select IBM ICSF Hardware and use SECUREZIP software facilities as a backup to ensure successful processing for the chosen method. This is the default setting.
SECUREZIP
Only use cryptographic routines provided by SecureZIP. No attempt will be made to select ICSF APIs.
Usage Notes
The value(s) for this command setting can be specified in the defaults module.
The last command setting for FACILITY_RANDOM takes precedence.
Exclusive use of IBM ICSF cryptographic services may be designated by eliminating “SECUREZIP” as a value from the list. However, if the required facility is not actively supported in the operating environment, the ZIP request will be rejected.
Because SECUREZIP supports all methods, placing it before other facility types in the list will effectively negate succeeding values.
Additional information regarding cryptographic facility availability and selection may be found in the SecureZIP Administrator’s Guide under “SecureZIP ICSF Operations” and “Cryptographic Facility Utility.”
–FILE_BUSY_WAITTIME
Synonyms Include: N/A
This command specifies how long PKZIPz should wait while continually retrying before it will terminate and give an error message or go on to further processing.
–FILE_BUSY_WAITTIME(<HHMMSSTH>)
HHMMSSTH:
HH - Hours
192
MM - Minutes
SS - Seconds
T - Tenths of a second
H - Hundredths of a second
00100000:
10 minutes is the default
–FILE_EXTENSION
Synonyms Include: –CNVEXT
- Cross Platform Compatible command (iSeries, OS/400, UNIX, and Windows).
This setting assists in transforming file names into an acceptable MVS data set name format during EXTRACT processing. When a file is extracted, and the file name within the archive contains an extension (defined as a period-separated suffix), the FILE_EXTENSION command specifies what to do with the extension. There are three options: DROP (the default), SUFFIX, or NAMEFILE.
–FILE_EXTENSION(DROP|SUFFIX|NAMEFILE)
DROP - The extension (which will drop the last data level of the archive File).
Example:
Given the file: FIRST/RATE/DATES/README.txt
and a command of: –FILE_EXTENSION(DROP)
the file will be: FIRST.RATE.DATES.README
the PDS will be: FIRST.RATE.DATES(README)
SUFFIX - The extension will be concatenated to the last data level without the delimiting period (note that any generated name longer than 8 characters will be truncated to 8 characters).
Example:
Given the file: FIRST/RATE/DATES/README.txt
and a command of: –FILE_EXTENSION(SUFFIX)
the file will be: FIRST.RATE.DATES.READMETX
the PDS will be: FIRST.RATE.DATES(READMETX)
NAMEFILE - The extension into a data level.
193
Example:
Given the file: FIRST/RATE/DATES/README.txt
and a command of: –FILE_EXTENSION(NAMEFILE)
the file will be: FIRST.RATE.DATES.README.TXT
the PDS will be: FIRST.RATE.DATES.README(TXT)
–FILENAME_API_ERRLIM
Synonyms Include: N/A
This command value is not currently used.
–FILENAME_API_ERRLIM(<threshold #>)
threshold # – Default 0
–FILENAME_API_ERROR
Synonyms Include: N/A
Identify the type of processing to occur when an API error occurs.
STOPRUN will trap any program exception, display the results of the trap and cause the end of the SECZIP execution.
ABEND will cause the API to allow an abend of the user API withour trapping the program exception and will subsequently allow a dump to occur. It will then result in the end of the SECZIP execution.
IGNORE will trap any program exception, display the results of the trap, and then continue with the next file.
–FILENAME_API_ERROR(STOPRUN|ABEND|IGNORE>)
–FILENAME_API_LANGUAGE
Synonyms Include: N/A
The language used to code the API. Basic Assembler Language (ASM) is the default.
194
–FILENAME_API_LANGUAGE(ASM|COBOL)
–FILENAME_API_NAME
Synonyms Include: N/A
The name of the filename API load module. You would place this load module into a JOBLIB, STEPLIB or a system linklist library.
–FILENAME_API_NAME(<module name>)
module name – Up to 8 character name of the load module to be used as the Filename API.
Note: Use of the NOAPI control card negates all USER API processing. Accordingly any information placed into the FILENAME_API control cards is ignored.
–FILENAME_API_PARM
Synonyms Include: N/A
This control card can be used to pass information to the User API.
–FILENAME_API_PARM(<user data>)
user data – Default blanks, can be up to 80 bytes
–FILENAME_API_TRACE
Synonyms Include: N/A
This allows headings, control blocks, registers, and data areas to be presented in SYSPRINT to help in the debugging of a User API.
0 = Trace Off
1 = Basic
2 = Medium
3 = Low Level
4 = Very Low Level
The higher the number the more volume of output.
195
–FILENAME_API_TRACE(0|1|2|3|4)
–FILENAME_API_WORKSIZE
Synonyms Include: N/A
The size of the work area to be used for the API. This area can be used to pass information between instances of the API being called and will be retained for the life of the run.
–FILENAME_API_WORKSIZE(<work size in bytes>)
work size – Default 4096 max is 32768
–FILENAME_ENCRYPTION
Synonyms Include: –ENCRYPT_FILENAMES –FNE
This command specifies whether the archive central directory is to be strongly encrypted during ZIP processing to protect the filenames and associated data set description information.
–FILENAME_ENCRYPTION(Y|N|blank)
Y - YES – Request that central directory encryption be performed for the output archive.
N - NO – Request that an unencrypted central directory be created in the output archive.
blank - Request that an unencrypted central directory be created for a new archive, and that the state of an input archive be retained when creating an updated output archive. This is the default setting as distributed, but may be changed in the defaults configuration module.
See also: PASSWORD, RECIPIENT
When FILENAME_ENCRYPTION is enabled, the settings for the following commands are involved: ENCRYPTION_METHOD, PASSWORD, RECIPIENT and SECURE_OPT_MSK3DES. If files are added or freshened during the update to the archive, the same encryption scheme will be used both for the central directory and the altered files.
Information in the local headers for each of the files in the archive will be masked or eliminated. Filenames normally stored in the local header preceeding each file will have a dynamically generated pseudo name assigned. ZIP and UNZIP operations ignore these names when processing files. (Only the true names stored within the encrypted central directory will be used for processing when the proper authorization is specified). The generated filenames may be different for each SecureZIP run. File attributes such as allocation, volume, DCB, and uncompressed size will not be stored in the local header area.
When FILENAME_ENCRYPTION is turned on, an additional benefit of archive Directory compression is introduced, further reducing the total size of the archive. The current
196
compression settings to be used for file compression are used to compress the archive Directory.
Because the entire central directory of the archive is encrypted, all filenames are encrypted.
Usage Notes
Password, Recipient, or both may be used to encrypt the archive central directory.
ENCRYPTION_METHOD must be set to use an algorithm of at least a 128-bit key length. ENCRYPTION_METHOD=STANDARD is 96-bit, and is not allowed for FILENAME_ENCRYPTION.
In order to perform any ZIP or UNZIP operation against an archive that has FILENAME_ENCRYPTION turned on, the correct password or one of the associated private-key certificates for one of the designated recipients must be provided.
SAVE_FILE_ATTRIBUTES will be restricted to CENTRAL or NONE. SecureZIP will automatically convert “BOTH” to “CENTRAL” and “LOCAL” to “NONE” to ensure that file attribute information is not viewable within the archive for added or changed files.
An archive previously having FILENAME_ENCRYPTION turned on may be updated (Add, Copy, Delete, Freshen). The encryption mode (password and/or recipient) and settings (algorithm and key length) will be retained as used in the original activation of Filename Encryption.
Once file names in an archive are encrypted, you cannot change the password or recipient list used.
An archive containing no previously encrypted files may be updated (Add, Copy, Delete, Freshen) and converted to a filename-encrypted archive. Files added, updated or freshened in the run will be encrypted with the specified encryption parameters. File data copied from the original archive will remain unencrypted, the filename associated with the file will be encrypted, and any carried-over file attributes from the local header will be retained. (If SAVE_FILE_ATTRIBUTES CENTRAL or NONE had been specified for the input archive when it was created, then there will be no exposure of file attributes).
When attempting to update archive containing previously encrypted files but not with FILENAME_ENCRYPTION, FILENAME_ENCRYPTION will be dynamically disabled, message ZPEN018W will be issued and a warning return code (4) for SecureZIP will be set while processing continues.
The ZIP archive_comment that is written at the end of the archive (if one is specified) is not included in the FILENAME_ENCRYPTION area. It will still be written in display text format (normally encoded in ASCII).
You cannot change the encryption on files that are already in an archive that contains encrypted file names when FILENAME_ENCRYPTION is retained for an updated archive.
An archive may be updated or copied using ARCHINDD and ARCHOUTDD to either enable or disable FILENAME_ENCRYPTION for the resulting output archive. An archive may not be transformed in place by using ACTION=COPY, however, an Add, Freshen, Update or Delete action will allow the mode of FILENAME_ENCRYPTION to be changed for a dynamically allocated archive.
Any files added or freshened in the archive when FILENAME_ENCRYPTION is enabled will be encrypted with the same settings used for the archive directory. Files may not be added or freshened “without” encryption while FILENAME_ENCRYPTION is enabled.
197
When a transformation from a Filename-encrypted archive to a nonFilename-encrypted is requested, the input archive with Filename Encryption enabled requires that update processing provide either password or Recipient information for access. Files being added or freshened will be encrypted with the mode and encryption algorithm specified in the command settings (not from the input archive). This means that the mode and algorithm for updated files may be different than that of the input archive. However, the mode used for access to the input archive will minimally be included for the updated file encryption.
When a transformation from a Filename-encrypted archive to a nonFilename-encrypted is requested, files may not be added or freshened directly with a removal of encryption (or reduction to “Standard” encryption). The input archive must first be transformed to a non-Filename Encryption format before unencrypted or “Standard” encryption files can be added or freshened.
If it is desirable to have an archive with some files unencrypted, first create an archive with no encryption, then update/copy the archive with FILENAME_ENCRYPTION enabled to encrypt the archive Central directory and optionally add files that are to be encrypted.
FILENAME_ENCRYPTION will be disabled for GZIP runs.
INCLUDE_SFX will be disabled when FILENAME_ENCRYPTION is enabled. The Self-extracting stubs provided do not support this feature. The appropriate PKWARE product should be obtained for the target platform in order to process encrypted filenames.
Restriction – Filename Encryption should not be attempted with more than approximately 100 recipients. The current code supports a 128K buffer to contain certain recipient certificate information.
Because Filename Encryption mirrors the previous recipient list during an archive update without having to re-access public key certificates, a significant amount of unnecessary processing can be avoided by providing only the private key certificate needed to facilitate update priviledges to the archive.
–FILENAME_SELECT_CASE
Synonyms Include: FILECASE_MIXED, FILECASE_UPPER
Affect archive filename selection case sensitivity.
–FILENAME_SELECT_CASE=M|U
When attempting to select files from an archive, case sensitivity is the default. By specifying FILENAME_SELECT_CASE=U, the file names in the archive and the filename command selections will be translated to Upper case before a comparison is performed. The “M” (mixed) option is the default, which means that case-sensitivity is honored during the match process.
The use of Upper can reduce the complexities of selecting files from an archive for View and Extract processing. However, unpredictable results may occur if multiple files in the archive use the same character strings with varying case.
This specification also affects the UNZIPPED_DSN selection command values. Although this provides a convenience for coding, archives that contain multiple files of similar names except for case-differentiation may require case-sensitive selection.
198
Note: The effect of this command setting is not positional within the command data stream. The last value set will be honored regardless of where data set names are in the stream.
–FILE_TERMINATOR
Synonyms Include: –TERM
- Cross Platform Compatible command (iSeries, OS/400, UNIX, and Windows).
–FILE_TERMINATOR(<delim chars>)
delim chars - These are the delimiter characters to be appended. There may be 0-4 characters specified in any combination:
CR - Appends an ASCII Carriage Return (hex 0D).
CZ - Appends a ASCII Ctrl-Z character (hex 1A).
LF - Appends a ASCII Line Feed character (hex 0A).
() - No delimiters at all.
Used In PKZIP Processing
When compressing a file as text (not binary), the FILE_TERMINATOR command specifies what character(s) to store at the end of the last record of the file to signal the end. When compressing a file as binary, the FILE_TERMINATOR command is ignored. (See also CRLF command for additional information regarding the interaction of DATA_DELIMITER and FILE_TERMINATOR for the last record of the file).
Used In PKUNZIP Processing
When decompressing a text file (not binary), the FILE_TERMINATOR command specifies what character(s) to find at the end of the last record of the file to signal the end. When decompressing a binary file the FILE_TERMINATOR command is ignored.
When Used in Either Type of Processing
The default is CRLFCZ if no FILE_TERMINATOR command is specified with the SECZIP program. With the PKUNZIP program the default is CRLFCZ if no characters are specified by FILE_TERMINATOR(). Otherwise a range of standard delimiters are used in the search which should satisfy most systems.
MS-DOS records use CRLFCZ for a delimiter.
UNIX records use LF for a delimiter.
When extracting the file(s), the same FILE_TERMINATOR command that was used to ZIP should be used to UNZIP to process the file correctly if non-standard delimiter characters were used.
199
The FILE_TERMINATOR characters should be different than the DATA_DELIMITER characters to make the last record distinct. Use a different combination of characters to create the distinction.
For example, these would not be distinct (note the same CRLF in the character set):
–DATA_DELIMITER(CRLF). –FILE_TERMINATOR(CRLFCZ)
or
–FILE_TERMINATOR(CZCRLF)
where a single record of CZ would be created.
These would be distinct: there is no duplication of character sets:
–DATA_DELIMITER(CRLF). –FILE_TERMINATOR(CZCRCZ).
–GDGALL_SUPPORT
Synonyms Include: –GDGALL, –NOGDGALL, –SELECT_GDGALL
This command determines whether all levels of a Generation Data Group (GDG) are retrieved and included in the archive.
–GDGALL_SUPPORT(Y|N)
Y - YES - All levels of the data set are retrieved.
N - NO - Only the current data set (Level 0) is retrieved.
–GZIP
Synonyms Include: –NOGZIP
- Cross Platform Compatible command (iSeries, OS/400, UNIX, and Windows).
This command syntax is retained for compatibility with command streams prior to release 9.0. See -ARCHIVE_ZIPFORMAT=GZIP, which replaces GZIP=Y.
–GZIP(Y|N)
Y – Synonym for -ARCHIVE_ZIPFORMAT(GZIP)
N – Synonym for -ARCHIVE_ZIPFORMAT(FULL)
Processing Notes
As of Release 9.0, the GZIP setting is no longer honored when defined in the defaults module. If GZIP is desired as the default, then set ARCHIVE_ZIPFORMAT=GZIP in the defaults module.
200
–GZIP_SUFFIX
Synonyms Include: N/A
- Cross Platform Compatible command (iSeries, OS/400, UNIX, and Windows).
This command may be used during UNZIP processing when there is no valid GZIP filename within the input GZIP. The archive input file name will be used, and the last level of the name will be replaced with the value of this field.
–GZIP_SUFFIX(<suffix>)
suffix - The name to be used as the last level of the filename. The default is “GZIPOUT”
–GZIPCRC_IGNORE
Synonyms Include: PROC_OPT6 (Maintenance command from release 5.6)
This command can be used during UNZIP processing when a GZIP source file and a “CRC ERROR” condition is encountered.
–GZIPCRC_IGNORE(Y|N)
The CRC ERROR condition may be raised if a GZIP source file has been transferred to the system with residual information at the end of the data set. (This can happen if the file transfer is done to a data set having a DCB RECFM=F/FB). The GZIP file format holds the CRC value positionally at the end of the file stream. If residual information is found, then UNZIP processing may not be able to correlate the CRC validation.
–HIERARCHY
Synonyms Include: –NOHIERARCHY
–HIERARCHY(Y|N)
Y - YES - Specifies that the entire data set name stored in the ZIP archive file is to be used to convert the file to an MVS format.
N - NO - Strips away higher level components and uses the lowest level of the data set component(s) as the member name when creating a file name in the PDS. It is used when converting a file from ZIP archive format to MVS format. The PDS should be specified with the command SELECT_FROM_PDS or ZIPCUR.
201
Example:
Given the file: TDS/DICT/DATA
and a command of: –HIERARCHY(Y)
the file will be: TDS.DICT.DATA
the PDS will be: TDS.DICT(DATA)
Example:
Given the file: TDS/DICT/DATA
and a command of: –ZIPCUR (MYRE.SPELL.CHK) –HIERARCHY(N)
the PDS will be: MYRE.SPELL.CHK(DATA)
If the PDS member already exists, you must replace it with OUTFILE_OVERWRITE or add it with INSERT_MEMBER to keep the member.
–INCLUDE_CMD
Synonyms Include:
Include an additional set of commands from a PDS or PDSE member.
–INCLUDE_CMD=ddname(member)
or
–INCLUDE_CMD=(member)
or
–INCLUDE_CMD=hlq.dsname(member)
If ddname is omitted, then a search is performed to locate a member in the data set specified via the DDNAME_PARMLIB specification (if one is allocated) or the PARMLIB_DSNAME_ZIP and PARMLIB_DSNAME_UNZIP settings.
If the data set is found to not be partitioned, or the member cannot be read, then processing will be terminated.
When multiple nodes (separated by ‘.’) are detected in the command parameter, the entire value is treated as a data set from which commands are to be included. This may either be a member of a PDS or a sequential data set.
Two members are included in PKWARE.MVS.INSTLIB (TOUNIX and TOMSDOS) to assist in cross-platform file transfers. The following example shows how to include the attributes required when sending text data to an MS-DOS platform.
202
//INSTLIB DD DISP=SHR,DSN=PKWARE.MVS.INSTLIB //SYSIN DD * -ARCHIVE_DSN(&SYSUID.DOS.ZIP) -INCLUDE_CMD=INSTLIB(TOMSDOS) ********************************************************************** * This sample command stream can be included with the command * * -INCLUDE_CMD=ddname(TOMSDOS) * * * * Set common parameters associated with transfering data to a * * workstation (assuming ASCII data translation). * * * ********************************************************************** * Have SECZIP translate EBCDIC (IBM-1047) to ASCII (IBM-850) -DATA_TYPE(TEXT) -TRANSLATE_TABLE_DATA(EBC#850) * Use x'0D0A' to delimit records -DATA_DELIMITER(CRLF) * No file terminator at the end of the stream -FILE_TERMINATOR() PKWARE.MVS.C(CCENCDK1) ZPAM030I OUTPUT Archive opened: MAS.DOS.ZIP ZPAM253I ADDED File PKWARE.MVS.C(CCENCDK1) ZPAM254I as PKZIP/DEV/C/CCENCDK1 ZPAM255I (DEFLATED 60%/57%) ORIG. SIZE 14,471; ZIP SIZE 6,235 ZPAM140I FILES: ADDED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Processing Notes
Multiple INCLUDE_CMD commands may be used in a single run.
When found in the primary command streams (SYSIN or EXEC PARM) or via the defaults module PARMLIB settings, the referenced command member is read immediately into the command stream at the point in which the INCLUDE_CMD command is encountered. This makes the commands positionally sensitive since additional commands that follow may override included commands.
Nesting of INCLUDE_CMD from within included command sequences is supported. However, the following should be noted:
The current included command stream is processed entirely before the nested include file is read. Assume that SYSIN has INCLUDE_CMD=dsn(A), member A has INCLUDE=dsn(B), and B has INCLUDE_CMD=dsn(C). As soon as INCLUDE_CMD=dsn(A) is encountered in the primary input stream, B will be opened and read completely. Regardless of where INCLUDE=dsn(B) is found within A, it will be queued for processing behind all of A’s commands. Then all of member B will be read and processed (and C will be queued behind it).
Once all nested includes have been processed, then control will be returned to reading the primary input stream immediately following the original INCLUDE_CMD request.
A recursion protection mechanism is built into the software to prevent loops due to command coding errors. Each INCLUDE_CMD value is tracked as it is encountered. If a duplicate INCLUDE_CMD value is found, it will be ignored and processing off commands in the current source will occur without opening (or queueing) the duplicate source.
Care should be taken to evaluate the include sequences or unexpected results may occur. If multiple sources have includes for the same member, then the first
203
occurrence encountered will include that member and subsequent includes will be ignored. If sequence-sensitive overrides are coded, the inclusion of a nested command sequence by another source may alter the expected result.
–INCLUDE_SFX
Synonyms Include: SELF_EXTRACTOR, SFX, MAKESFX, SFX_AIX, SFX_HPUX, SFX_LINUX2I, SFX_LINUX, SFX_SUN, SFX_WINDOWS
Create a self-extracting archive by prefixing the archive with a self-extraction program appropriate to a target system.
Note: This feature is only available with ARCHIVE_ZIPFORMAT=FULL.
–INCLUDE_SFX=self_extraction_program_name self_extraction_program_name –
SFXAIX IBM AIX Version 4.0 and above
SFX_AIX may be specified as a shortcut
SFXHP HP/UX Version 9.0 and above
SFX_HPUX may be specified as a shortcut
SFXLNX2I LINUX Kernel 2.x for Intel (target system run-time requirements: Reference PKZIP Support Notice #13 02/16/2001 regarding LINUX target system support files ld.so-1.9.5-13.i386.rpm and libc-5.3.12-31.i386.rpm)
SFX_LINUX or SFX_LINUX2I may be specified as a shortcut
SFXSUN Sun Solaris 2.3 (SunOS 53) and above
SFX_SUN may be specified as a shortcut
SFXWIN Microsoft Windows (95 and above)
SFX_WINDOWS may be specified as a shortcut
When creating an archive for self-extraction to take place on a different platform, it is important to also include commands that are associated with properly converting the record management and text character set of the data file. INCLUDE_CMD(TOMSDOS) and INCLUDE_CMD(TOUNIX) will assist you in creating a file that will successfully extract on the target system.
The self extracting programs are held as binary entities in the PKZIPz load library. The appropriate member is loaded and the executable data copied to the beginning of the archive as a preamble when requested.
The resulting archive can still be processed by PKZIPz as a normal ZIP archive.
When an input archive containing a self-extraction preamble is passed to PKZIPz for SECZIP processing and no value is supplied by INCLUDE_SFX , the PREAMBLE is removed when writing the new archive.
204
A self-extracting archive can be created from an existing archive by using the ACTION(COPY) command along with INCLUDE_SFX. If the original archive contained a preamble, it will be removed and the newly specified preamble will be inserted.
When transferring a self-extracting archive to a target system, be sure to transfer the archive in BINARY format and adhere to requirements for executables in that environment. (For example, a Windows program should be saved with an application extension of EXE, and a UNIX file attribute should have executable authorization set via the UNIX chmod command).
The self-extraction programs provided are at the 2.5 level of PKZIP. As such, the following restrictions apply to the operation of the self-extraction program(s). Care should be taken to control the creation of the self-extracting archive within these restrictions, although the resulting archive may still be processed with PKZIP programs at higher levels that support these features.
The number of files in the archive should be limited to 65,535 or less.
Strong Encryption is not supported.
Authentication of digital signatures is not supported (although the signatures within the archive will be maintained and can be authenticated by appropriate SecureZIP products).
The size of the archive should not exceed 2 gigabytes.
The uncompressed size of individual files should be less than 2 gigabytes (4 gigabytes on some UNIX systems).
To assist in the usage of the self-extraction programs on the target systems, some of the command parameters are listed below. Note that some parameters may not be valid on all systems. By executing the transferred self-extracting archive on the target system with “-help”, the commands syntax appropriate to that system will be displayed.
Usage: sfx.exe [options] [.ZIP archive] [files...]
Where sfx.exe = the name of the self-extracting executable file
Option
after extract files that are newer than or equal to a specified date
Suboptions:
"date specification" [format: mmddyy or mmddyyyy]
Example: sfx.exe -aft=12311999 file.zip
before extract files that are older than a specified date
Suboptions:
"date specification" [format: mmddyy or mmddyyyy]
Example: sfx.exe -bef=12311999 file.zip
console display the contents of specified archived files on your screen
Example: sfx.exe -con= file.zip readme.txt
directories recreate directory path while extracting including any sub-directories
Example: sfx.exe -dir file.zip
205
Option
exclude exclude specified files from being extracted
Example: sfx.exe -exc=*.txt file.zip
extract extract files from the .ZIP archive
Suboptions:
all [extract everything in archive]
freshen [extract if newer than destination copy]
update [extract if newer or not in destination directory]
Example: sfx.exe -ext=all file.zip
help display help screen
Example: sfx.exe -help
Id preserve original file uid/gid. Must be root/file owner (UNIX only)
include include specified files for extraction
Example: sfx.exe -inc=*.txt file.zip
larger extract files that are the specified size (in bytes) and larger
Suboptions:
a numerical value (in bytes) that indicates a minimum desired file size
Example:sfx.exe -larger=400
license displays license information
Example: sfx.exe -lic
locale reads and/or adjusts the locale variable for date and time format input
Suboptions:
environment [read system variable and apply accordingly]
"valid country name" [for example localExamplermany]
Example: sfx.exe -loc=us -aft=12311999 file.zip
lowercase change filenames to lower case on extraction
Example: sfx.exe -lowercase
mask remove specified file attributes upon extraction
Suboptions:
archive [mask archive attribute from file(s)/folder(s)]
hidden [mask hidden attribute from file(s)/folder(s)]
system [mask system attribute from file(s)/folder(s)]
readonly [mask read-only attribute from file(s)/folder(s)]
none [do not mask attributes from file(s)/folder(s)]
all [mask all attributes from file(s)/folder(s)]
Example: sfx.exe -mask=archive,readonly file.zip
206
Option
more display output one screen at a time
Example: sfx.exe -more file.zip
newer process only those files that are newer than a specified (calendar) day in the past
Suboptions:
a numerical value (in calendar days) that indicates some
date in the past relative to the current date
Example: sfx.exe -newer=2
noextended suppress the extraction of extended attributes
Example: sfx.exe -noex file.zip
older process only those files that are older than a specified (calendar) day in the past
Suboptions:
a numerical value (in calendar days) that indicates some
date in the past relative to the current date
Example: sfx.exe -older=2
overwrite overwrite existing files
Suboptions:
prompt [prompt before overwriting]
all [always overwrite]
never [never overwrite]
Example: sfx.exe -o=all file.zip
password specify a decryption password
Example: sfx.exe -pass=grendel file.zip
print print the specified archived file
Suboptions:
"print device name" [for example print=lpt1]
Example: sfx.exe -print=lpt2 file.zip readme.txt
silent suppress warning messages when extracting
Example: sfx.exe -silent file.zip
smaller extract files that are the specified size (in bytes) and smaller
Suboptions:
a numerical value (in bytes) that indicates a maximum desire file size
Example:sfx.exe -smaller=400
207
Option
sort sort files when extracting
Suboptions:
crc [sort by crc value]
date [sort by date of the file]
extension [sort by file extension]
name [sort by file name]
natural [sort in the order that the file was archived]
ratio [sort by compression ratio]
size [sort by file size]
none [do not sort]
Example: sfx.exe -sort=size file.zip
test test the integrity of archived files
Suboptions:
all [test everything in archive]
freshen [test if newer than destination copy]
update [test if newer or not in destination directory]
Example: sfx.exe -test=all file.zip
times preserve specified file date/time stamp
Suboptions:
access [preserve accessed date/time stamp on extraction]
modify [preserve modified date/time stamp on extraction]
create [preserve created date/time stamp on extraction]
all [preserve all date/time stamps on extraction]
none [do not preserve date/time stamps on extraction]
Example: sfx.exe -time=access,modify file.zip
translate translate the end of line sequence for give operating system
Suboptions:
DOS [convert to DOS style line endings]
MAC [convert to MAC style line endings]
unix [convert to unix style line endings]
Example:sfx.exe -translate=unix
208
Option
version display SFX version and return appropriate value to the shell
Suboptions:
major [return major version number]
minor [return minor version number]
step [return step or patch version number]
Example: sfx.exe -ver=step
volume restore the volume label when extracting
Example: sfx.exe -vol file.zip
warning prompt to continue after warning message
Example: sfx.exe -warn file.zip
–INFILE
Synonyms Include: –INDD, –IFILE, –INFILE_DD
The INFILE command identifies the DD statement that further describes the file to be compressed.
–INFILE(<ddname>[,member1][,member2][,…membern])
ddname - The name of the DD job step listed in the JCL.
Member1-n - 0 to n member names that identify specific members within the PDS (described in the <ddname> used in the job step).
The DD statement may describe a sequential data set, an entire PDS or a member of a PDS, or even a generation of a GDG.
If a member of a PDS is to be compressed, there are two methods of identifying that member.
First, using just the DD statement where the individual member is described in the DD statement and INFILE refers to that DD statement.
Example: //INPUT DD DISP=SHR, DSN=MY.DATA.FILES(.FIRST) . . . –INFILE(INPUT)
Second, using the command where the entire PDS is described in the DD statement and then the INFILE command refers to that DD statement as well as the individual member name(s) to use.
209
Example //INPUT DD DISP=SHR, DSN=MY.DATA.FILES . . –INFILE(INPUT,FIRST, SECOND,FIFTH)
Note that more than one member may be indicated with the command.
If no members are indicated, the entire PDS is used.
Multiple INFILE commands can be used.
See <data set name> for data set naming capabilities.
–INSERT_MEMBER
Synonyms Include: –INSERTMEMBER, –NOINSERTMEMBER
The INSERT_MEMBER command is used to add a member to an existing PDS.
–INSERT_MEMBER(Y|N)
Y - YES - Specifies that the newly extracted member will be added and become a new member of an existing data set.
N - NO - Specifies that the member will not be added and the process will fail with an error message.
See OUTFILE_OVERWRITE to update a data set in an existing PDS.
–KEY_PROTECT_LEVEL
Synonyms Include: –KEYPROTECT1, –KEYPROTECT2
Requires SecureZIP
–KEY_PROTECT_LEVEL(1|2)
When using advanced encryption (see ENCRYPTION_METHOD) during a ZIP operation, additional information is stored in the ZIP archive pertaining to the encryption keys. This information is also encrypted to further secure the file data.
The use of this parameter will affect the size of the resulting archive. KEY_PROTECT_LEVEL(1) will use approximately 100 more bytes per file in the archive, while KEY_PROTECT_LEVEL(2) will require 340 more bytes per file. Level(2) is the preferred setting for increased security.
210
–LDAP_ENCRYPT_CERT_SELECT
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
LDAP_ENCRYPT_CERT_SELECT(ALL|FIRST|LAST|LATEST|FIRST_ENCRYPT |LAST_ENCRYPT|LATEST_ENCRYPT)
This command assists in restricting the number or type of certificates being used to represent a user or organization for each encrypted file.
When using LDAP to locate Public-key certificates for recipients, it is possible to locate more than one certificate for a target recipient. For example, if a user obtains a new certificate each year, then multiple certificates may represent that user within the LDAP. It may also be possible for a user to have certificates from multiple Certificate Authorities (e.g. Verisign, Thawte), or multiple certificates for different purposes (encryption vs. signing).
In any of the above conditions, a ZIP process may result in multiple recipient certificates being processed for the same target recipient (person or organization). Some organizations may desire to restrict the type or quantity of certificates being used for encryption. This can save processing resources and ZIP archive space.
Parameters:
ALL – Every certificate located in an LDAP Server matching the search criteria will be added as a viable recipient.
FIRST – For each LDAP entry matching the search criteria, only the first certificate stored in that entry will be included, regardless of use type designated in the certificate or its valid date period. This use case depends on the certificate loading order used in the LDAP.
LAST – For each LDAP entry matching the search criteria, only the last certificate stored in that entry will be included, regardless of use type designated in the certificate or its valid date period. This use case depends on the certificate loading order used in the LDAP.
LATEST – For each LDAP entry matching the search criteria, the most recent certificate stored in that entry will be included, regardless of use type designated in the certificate. Note that if multiple certificates are found within an LDAP entry, certificates with their validity period not yet starting will be excluded unless they are the only certificates within the entry. In that case, the first certificate found will be selected.
FIRST_ENCRYPT – For each LDAP entry matching the search criteria, the first certificate found with a use type set for encryption stored in that entry will be included, regardless of its valid date period. This use case depends on the certificate loading order used in the LDAP. If no entries are found with the use type set to encryption, then the first certificate found in the LDAP entry will be selected.
LAST_ENCRYPT – For each LDAP entry matching the search criteria, the last certificate found with a use type set for encryption stored in that entry will be included, regardless of its valid date period. This use case depends on the certificate loading order used in the LDAP. If no
211
entries are found with the use type set to encryption, then the first certificate found in the LDAP entry will be selected.
LATEST_ENCRYPT – For each LDAP entry matching the search criteria, the most recent certificate found with a use type set for encryption also having the “best” date range for its validity period. This use case depends on the certificate loading order used in the LDAP. If no entries are found with the use type set to encryption, then the most recent certificate found in the LDAP entry will be selected. Note that if multiple certificates are found within an LDAP entry, certificates with their validity period not yet starting will be excluded unless they are the only certificates within the entry. In that case, the first certificate found will be selected.
Note: Regardless of the option selected, at least one certificate will be selected from an LDAP entry. Each certificate selected must be in valid X.509 Public-key format.
–LICENSE_HLQ
Synonyms Include: N/A
This command specifies the high level qualifier to be used in locating the License Control Data set. This should be specified in accordance with directions provided by the Systems Programmer responsible for setting up the product and maintaining its licensing options. It will be used to allocate the sezczip.mvs.LICENSE data set during execution.
–LICENSE_HLQ(<hlvl>)
hlvl - High level qualifier used for allocation (PKZIP.MVS is the default for PKZIP, SECZIP.MVS is the default for SecureZIP).
–LMOD_SUPPORT
Synonyms Include: N/A
- This is an MVS command only.
- Be aware that if this command is used incorrectly, you could incur problems.
This command determines whether PKZIPz processing will dynamically turn on the commands of DATA_TYPE(BINARY), SAVE_LRECL, and SAVE_FILE_ATTRIBUTES for PDS members that have been detected as Load Modules. These modules will then be reconstructed during UnZip processing.
This feature allows text-based non-load module files to be zipped during a single pass along with load libraries. One might use this feature to process a PDS containing both load modules and text files in a single pass.
212
–LMOD_SUPPORT(Y|N)
Y - YES - Turn on LMOD_SUPPORT support. Zip processing will dynamically turn on SAVE_LRECL and DATA_TYPE(BINARY) for PDS members detected as being load modules.
N - NO - Do not turn on LMOD_SUPPORT support.
See DATA_TYPE(BINARY), SAVE_FILE_ATTRIBUTES, and SAVE_LRECL for additional information.
LICENSE_WTO_INFO
Synonyms Include:
The license feature warning messages will be displayed on the console as well as in the printed output of each run. If you do not wish to display the messages on the console change the defaults module to LICENSE_WTO_INFO=N. (Specifying this operation as a command will not affect license messaging that occurs prior to command inputs).
LICENSE_WTO_INFO=Y|N
This setting is specified in the defaults module only.
–LOGGING_LEVEL
Synonyms Include: –VERBOSE, –Q, –QUIET
This command specifies the level (or quantity) of messages that will be output from PKZIPz to SYSPRINT.
–LOGGING_LEVEL(NORMAL|QUIET|VERBOSE)
NORMAL - Specifies that a standard set of messages will be output to SYSPRINT.
QUIET - Specifies that no messages are issued, although return codes will be set when errors occur. This option is normally used when calling from a CLIST or another program where you will not immediately view the output (as in ISPF execution).
VERBOSE - Specifies that a more detailed level of messages will be output to provide in-depth processing information.
Dynamic Allocation Parameters used to create and access files.
Dynamic Allocation error codes.
System SORT messages (TRACE_SORT (4) may provide more).
Specific SECZIP messages.
213
–MASTER_RECIPIENT
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
MASTER_RECIPIENT(cert_store_type:selection[,R])
This command has the same format as RECIPIENT, and may be specified either through the Defaults module (ACZDFLT) or commands. The specification of MASTER_RECIPIENT does not trigger encryption to take place during ZIP processing in the same way as RECIPIENT. However, once encryption is specified, the value of MASTER_RECIPIENT is implicitly included in the run as if a RECIPIENT command had been invoked.
A master recipient, also known as a contingency key, is a global, enterprise-defined RECIPIENT included for administrative access. A contingency key enables the enterprise to decrypt and access the file(s) when other RECIPIENTs are no longer able or eligible.
Supplemental MASTER_RECIPIENT commands may be provided via the primary SYSIN input stream, or indirectly from either the SECUREZIP_CONFIG or INCLUDE_CMD specifications. They will be internally converted to RECIPIENT commands for processing.
MASTER_RECIPIENT settings are cumulative. Therefore a setting in the defaults module cannot be overridden or eliminated from an execution.
The “R” (required) flag should be set to guarantee that an archive cannot be created without the specified key.
–MEMORY_MODEL
Synonyms Include: –MEM_MODEL, –MEM_MDL, –SMM, –MMM, –LMM, –MMS, –MML
–MEMORY_MODEL(SMALL|MEDIUM|LARGE)
MEMORY_MODEL(SMALL|MEDIUM|LARGE) controls where file management control blocks are held, such as, control blocks describing an archive file with its attributes, and the amount of storage than can be used for compression control tables.
When MEMORY_MODEL(LARGE) is specified or defaulted, all of the file management control blocks are held in 31-bit virtual storage and the largest compression tables are used (providing the best compression possible for the Compression_Level selected).
When either SMALL or MEDIUM are specified, the file descriptor information is spilled to a set of work files to be sorted, merged and selected. Note that file descriptors are built for both files existing in the input archive and new files to be selected, so the aggregate count must be managed. Approximate sizes for each file descriptor are as follows:
214
VSAM - 2.5K.
Sequential - 800 bytes.
PDS/PDSE - 800 bytes for base data set + 224 bytes per member.
–MULTI_THREAD_LIMIT
Synonyms Include: –TASKS
To specify more than one task to be used while compressing a data set(s), use ARCHIVE_MGMTCLASS. Some systems have more that one CPU and can run subtasks to aid in processing. The compression of a data set would then run with two or more subtasks (depending upon the specified amount). These subtasks would run in parallel and speed processing time, improving performance for the processing of multiple data sets.
–MULTI_THREAD_LIMIT(<amount>)
amount - Specifies the maximum number of subtasks that may be used by PKZIPz to compress data sets. The <amount> should not exceed twice the number of CPU’s on a system. Should this command be used on a single CPU system, the results are undefined. An amount of 3 is the default.
ZIP processing speed can improve with this command, however, actual performance is dependent on the type of data sets that are processed.
Data sets within a PDS are processed within the same subtask unless the data sets are individually identified in separate data set definitions.
Some processing functions require that the MULTI_THREAD_LIMIT operate at 1. In most instances PKZIP and PKUNZIP will automatically set the active value to 1 when required, however you must use MULTI_THREAD_LIMIT(1) when you are compressing multi-file tape data sets from the same volume.
–NOAPI
Synonyms Include: N/A
–NOAPI
The Language Environment CEEPIPI environment associated with User API programs (such as DATA_TRANS_API) will not be initialized. This is important for Language Environment operations that do not support CEEPIPI being in operation (such as C++ calling SecureZIP ).
This command must be passed as an EXEC PARM command.
When NOAPI is in use, the DATA_TRANS and FILENAME APIs are not available for use.
215
–NOSYSIN
Synonyms Include:
–NOSYSIN
The SYSIN data set will not be opened if -NOSYSIN is specified as an EXEC PARM or in the PARMLIB configuration file. The command has no effect if placed within the SYSIN command stream.
This command is useful when calling the SECZIP program from another program. The SYSIN passed to the calling program will not be effected by the SECZIP program processing in this situation. See “Invoking the PKZIP and SecureZIP for z/OS Utility” in Chapter 5.
–ON_FILE_ACCESS_ERROR
Synonyms Include: –FILESELERR
In PKZIP Processing If an access problem occurs during the ZIP processing of an input file or a temporary archive, the ON_FILE_ACCESS_ERROR command specifies whether to terminate processing or ignore the error and continue. The default is to allow for compatibility.
–ON_FILE_ACCESS_ERROR(STOP|TERMINATE|TOLERATE| IGNORE[,WARNONBUSY]|[,WARNIFBUSY])
STOP - Processing halts when an access error is detected.
TERMINATE - Processing halts when an access error is detected.
TOLERATE - Processing continues with the next file. Error return codes and messages of the problem files are produced.
IGNORE - Processing continues with the next file. Error return codes and messages of the problem files are produced.
WARNIFBUSY - Processing continues with the next file, and the “busy” files are reported as a warning. This is an option to STOP or TOLERATE. Without STOP or TOLERATE specified, busy files will be skipped.
WARNONBUSY - Same as WARNIFBUSY.
Note: This is different from a similar command, –ON_FILE_IO_ERROR which refers to file errors during a read.
216
–ON_FILE_IO_ERROR
Synonyms Include: –FILEPROCERR
In PKZIP Processing If an I/O problem occurs during ZIP processing of an input file or a temporary archive, the ON_FILE_IO_ERROR command specifies whether to terminate processing or ignore the error and continue.
–ON_FILE_IO_ERROR(STOP|TERMINATE|TOLERATE|IGNORE)
STOP - Processing halts when an I/O error is detected.
TERMINATE - Processing halts when an I/O error is detected.
TOLERATE - Processing continues with other files. Should all files receive errors, the archive may be empty as no file processing occurred.
IGNORE - Processing continues with other files. Should all files receive errors, the archive may be empty as no file processing occurred.
In either case, the SECZIP program will create a return code and error message(s) indicating the problem.
Note: This is different from a similar command, –ON_FILE_ACCESS_ERROR which refers to file errors during access, before the file is read.
Used In PKUNZIP Processing
If an I/O problem occurs during ZIP processing of an output file, the ON_FILE_IO_ERROR command specifies whether to terminate processing or ignore the error and continue.
–ON_FILE_IO_ERROR(STOP|TERMINATE|TOLERATE|IGNORE)
STOP - Processing halts when an I/O error is detected.
TERMINATE - Processing halts when an I/O error is detected.
TOLERATE - Processing continues with other files following an I/O error.
IGNORE - Processing continues with other files following an I/O error.
In either case, the PKUNZIP program will create a return code and error message(s) indicating the problem.
Note: This is different from a similar command, –ON_FILE_ACCESS_ERROR which refers to file errors during access, after the file is extracted.
217
–OUTFILE_BLKSIZE
Synonyms Include: –OUTBLKSIZ, –OUTBLKSIZE
The OUTFILE_BLKSIZE command specifies the block size to be used when extracting to a dynamically created data set.
–OUTFILE_BLKSIZE(<block size>)
block size - The block size to be used for a newly created data set.
If the block size is not specified by this command, the size is taken from the information stored in the archive. If neither is available, a default size of 6160 bytes is set (assuming that an OUTFILE_DATACLASS was not specified, in which case the default is not used).
A value of zero will cause the PKUNZIP program to calculate a block size for sequential or PDS files. However, do not use a value of zero for undefined files (OUTFILE_RECFM(U)) as the resulting calculated block size may not be appropriate.
–OUTFILE_DATACLASS
Synonyms Include: –OUTDCLASS
This command pertains to DF/SMS allocation of new files when doing PKUNZIP processing. If you specify these classes, they will be passed to DF/SMS when data set allocation occurs.
–OUTFILE_DATACLASS(<SMS Data Class>)
See IBM’s DF/SMS manuals for further information about this parameter.
A new parameter option for SMS classes has been introduced to override a DATACLASS in the archive.
_NONE_
Example of change:
OUTFILE_DATACLASS=_NONE_
When specified, the DATACLASS in the archive is ignored. The RECFM, LRECL, and BLKSIZE will be taken from the original file in the archive.
An ACZDFLT parameter of _NONE_ will override all DATACLASSes in all archives. The data class specified in an OUTFILE_DATACLASS command override is applied to extracted file(s).
Note that during EXTRACT processing to a dynamically allocated data set, an installation SMS ACS routine may assign a DATACLASS outside of UNZIP’s control. The _NONE_ specification negates the DYNALLOC (SVC99) parameter request for DATACLASS by UNZIP, but the installation can still generate an override. This has the potential for assigning DCB attributes that are incompatible with the file data. Care should be taken when using SMS data class attributes to ensure that the installation assigns correct values.
218
–OUTFILE_DD
Synonyms Include: –OUTDD, –OFILE, –OUTFILE, –OUT_FILE
The OUTFILE_DD command identifies the DD statement that further describes the data set into which the files are to be extracted.
–OUTFILE_DD(<ddname>)
ddname - The DD statement in the JCL that identifies the data set to which files are extracted. When using OUTFILE_DD, allocation and attribute information should be provided in the JCL for the output file.
Multiple OUTFILE_DD commands may not be used. All extracted data is written to the target data set.
Other UNZIP commands are related to the function of OUTFILE_DD and may not be needed when OUTFILE_DD is used. They are the following:
FILE_EXTENSION - Specifies DROP, SUFFIX, or NAMEFILE to tell what to do with file extensions when extracting. The DD statement will determine the name of the output file.
OUTFILE_LRECL, OUTFILE_BLKSIZE, and OUTFILE_RECFM - Commands pertaining to dynamic creation of an output file are ignored when OUTFILE_DD is used.
UNZIPPED_DSN - Specifies exactly what files are to receive the extracted data. This file is determined in the DD statement, but the member name may be affected with the UNZIPPED_DSN command in operation.
–OUTFILE_DIR_BLOCKS
Synonyms Include: –OUTDIRBLKS, –OUTFILE_DIRBLKS
This command specifies the number of directory blocks to be used when a PKUNZIP process requires that a partitioned data set (PDS) is to be created. When OUTFILE_DSNTYPE is PDS or extended attributes are used to create the output file, then OUTFILE_DIR_BLOCKS can be used to specify or override the number of directory blocks to be allocated.
–OUTFILE_DIR_BLOCKS(<blocks>)
blocks - An 8-character field specifying the number of directory blocks to be allocated for a partitioned data set.
00000010 - Ten directory blocks is the default.
219
–OUTFILE_DSNTYPE
Synonyms Include: –OUTFILE_DSORG, –OUT_DSORG, –MAKEPDS, –MAKEPDSE, MAKELIBRARY, –MAKESEQ, –MAKEVSAM, –MAKEESDS
The OUTFILE_DSNTYPE command determines the type of output file to be created. This command overrides any stored file attributes.
–OUTFILE_DSNTYPE(SEQ|PDS|PO|PDSE|LIBRARY|VSAM)
If the Modifier Is SEQ
The extracted file will be a sequential data set.
Example:
Given the ZIP file: MY/DATA/SOURCE/ACCOUNTS
and a command of: –OUTFILE_DSNTYPE(SEQ)
the extracted file will be:
MY.DATA.SOURCE.ACCOUNTS
If the Modifier Is PDS, PDSE, PO, or LIBRARY
The extracted file will be a partitioned data set. The member name comes from the lowest level of the source data set name. If the PDS receiving the file already exists, you must specify INSERT_MEMBER(Y) or OUTFILE_OVERWRITE(Y) to determine what to do with the additional PDS file.
Example:
Given the ZIP file: MY/DATA/SOURCE/ACCOUNTS
and a command of: –OUTFILE_DSNTYPE(PDS)
the extracted member will be:
MY.DATA.SOURCE(ACCOUNTS)
If the Modifier Is VSAM
The extracted file will be a VSAM file.
220
Example:
Given the ZIP file: MY/DATA/SOURCE/ACCOUNTS
and a command of: –OUTFILE_DSNTYPE(VSAM)
the extracted cluster name will be:
MY.DATA.SOURCE.ACCOUNTS
–OUTFILE_LRECL
Synonyms Include: –OUTLRL –OUTLRECL
This command specifies the logical record length to be used for a new output file. It does not override an existing record length that is specified in JCL or for a data set that already exists.
–OUTFILE_LRECL(<length>)
length - An 8-character field specifying the logical record length.
00000080 - Eighty is the default record length.
–OUTFILE_MGMTCLASS
Synonyms Include: –OUTMCLASS
This command pertains to DF/SMS allocation of new files when doing PKUNZIP processing. If you specify these classes, they will be passed to DF/SMS when data set allocation occurs.
–OUTFILE_MGMTCLASS(<SMS Management Class>)
See IBM’s DF/SMS manuals for further information about this parameter.
–OUTFILE_OVERWRITE
Synonyms Include: –OVERWRITE, –NOOVERWRITE
The OUTFILE_OVERWRITE command is used to update an existing file or member within a PDS.
–OUTFILE_OVERWRITE(Y|N)
Y - YES - The newly extracted data set will overwrite the data in an existing data set of the same name.
N - NO - The new data set will not overwrite an existing data set and the process will fail with an error message.
See INSERT_MEMBER to add a data set to an existing PDS.
221
–OUTFILE_PDS_ENQ
Synonyms Include: N/A
The OUTFILE_PDS_ENQ command governs the level of disposition that will be used for a PDS or PDSE when processing an EXTRACT request. This affects both the EXTRACT job and other users in the system who have an existing PDS/PDSE open.
–OUTFILE_PDS_ENQ(OLD|SHR)
OLD - Specifies that a DISP=OLD be used.
SHR - Specifies that a DISP=SHR be used.
The greatest level of integrity is reached when jobs use DISP=OLD at the data set level. However, when PDS data sets or PDSE Libraries are held open in long running jobs (such as an online system), it is not possible to use DISP=OLD in the SECZIP program to update a member.
DISP=SHR will result in the SECZIP program processing the PDS directory and its members without full data set serialization. However, some level of protection is provided as follows:
During an EXTRACT process, PKUNZIP will test for an SPFEDIT ENQ on the PDS/PDSE member. If one exists in the system, then that member will be bypassed.
The operating system will provide protection for jobs using DISP=OLD:
When another job holds the dataset with DISP=OLD, the SECZIP program will fail to obtain an allocation to the dataset.
If the SECZIP program is updating the dataset and another job starts with DISP=OLD in its JCL, that job will wait until the SECZIP program closes and frees the file.
If the SECZIP program is updating the dataset and another job or user attempts a dynamic allocation with DISP=OLD, that allocation request will fail.
The operating system may provide update protection for two different jobs attempting DISP=SHR updates. For example:
If an IEBCOPY update is being performed against a PDS with DISP=SHR and SECZIP is running with –OUTFILE_PDS_ENQ(SHR), the SECZIP program may experience a system abend 213-30 when attempting to open the PDS directory. This is the way the system provides PDS directory integrity.
Likewise, if the SECZIP program already has the PDS/PDSE open for output, the same IEBCOPY step in the other job would receive the 213-30 abend.
–OUTFILE_RECFM
Synonyms Include: –OUTTYPE –OUTRECFM
The OUTFILE_RECFM command specifies the record format of the records in a newly extracted data set. If not specified, the information is taken from the attributes stored in the ZIP archive.
222
–OUTFILE_RECFM(U|F|FA|FB|FBA|FBM|FBS|FM|V|VA|VB|VBA|VBM|VM)
U - Undefined records.
F - Fixed records.
FA - Fixed records with ISO/ANSI control characters.
FB - Fixed-Block records (note also that this default is ignored if an associated SMS command of OUTFILE_DATACLASS is used).
FBA - Fixed-Block records with ISO/ANSI control characters.
FBM - Fixed-Block records with Machine control characters.
FBS - Fixed-Block Standard records.
FM - Fixed records with Machine control characters.
V - Variable records.
VA - Variable records with ISO/ANSI control characters.
VB - Variable-Block records.
VBA - Variable-Block records with ISO/ANSI control characters.
VBM - Variable-Block records with Machine control characters.
VBS - Variable-Block-Spanned records.
VM - Variable records with Machine control characters.
VS - Variable-Spanned records.
An undefined specification (U) will cause any OUTFILE_LRECL specifications to be ignored. Similarly, any of the unblocked specifications will cause OUTFILE_BLKSIZE specifications to be ignored.
–OUTFILE_SPACE_MULTIVOL
Synonyms Include: N/A
The OUTFILE_SPACE_MULTIVOL command controls whether the dynamic allocation of a new non-VSAM output data set will request multiple volumes when OUTFILE_DATACLASS is not in effect.
–OUTFILE_SPACE_MULTIVOL=Y|N
N - When a value of “N” is specified, or an OUTFILE_DATACLASS is specified, SecureZIP does not provide a volume count in the dynamic allocation request. When multiple volumes are required to hold the output file under this condition, the operating system may reject the volume extension with an associated IEC032I-04 E37 error.
Y - When “Y” is specified without an OUTFILE_DATACLASS, a maximum of 59 volumes will be requested in the DYNALLOC request. When this option is enabled, the catalog will show the output data set as being a multi-volume data set.
223
The message IGD17271I Allocation has been allowed to proceed for data set may appear in the JOB log from the system, but this will not affect SECZIP processing.
Note: See the SecureZIP for z/OS System Administrator’s Guide for more information on SMS dataclass considerations. See also the section “Large File Considerations” in Chapter 8 for discussions regarding SMS class controls of extended size data sets.
–OUTFILE_SPACE_PRIMARY
Synonyms Include: –OUTPRIMARY
This command specifies the number of allocation units in the primary extent to be allocated to a newly extracted data set.
The default is not used if OUTFILE_DATACLASS is specified.
–OUTFILE_SPACE_PRIMARY(<allocation units>)
allocation units - This an 8-character field specifying the number of allocation units for the primary extent allocation.
00000010 - Ten is the default.
–OUTFILE_SPACE_RLSE
Synonyms Include: –OUTFILE_RLSE, –OUTFILE_RELEASE, –OUTFILE_SPACE_RELEASE, –OUTRLSE, –OUTNORLSE
This command indicates that when a new file is closed using PKUNZIP processing, additional cylinders or tracks should be released from the allocation.
–OUTFILE_SPACE_RLSE(Y|N)
Y - YES - The deallocated free space is released following compression. This is the default action taken for sequential data sets.
N - NO - The deallocated free space is not released following compression. This is the default action taken for partitioned data sets (since the extra space may be needed by other members within the same PDS).
–OUTFILE_SPACE_SECONDARY
Synonyms Include: –OUTSECONDARY
This command specifies the number of allocation units in the secondary extent to be allocated to a newly extracted data set.
The default is not used if OUTFILE_DATACLASS is specified.
224
–OUTFILE_SPACE_SECONDARY(<allocation units>)
allocation units - This an 8-character field specifying the number of allocation units for the secondary extent allocation.
0000010 - Ten is the default.
–OUTFILE_SPACE_TYPE
Synonyms Include: –OUTSPACE
This command specifies the type of allocation units that are used at the allocation of a newly extracted data set. The allocation units may be one of five choices with CYL (cylinders) as the default. Note that the default is not used when OUTFILE_DATACLASS is specified.
–OUTFILE_SPACE_TYPE(<TRK|CYL|BLK|MB|KB>)
TRK - (also TRKS and TRACKS) Allocation by tracks.
CYL - (also CYLS and CYLINDERS) Allocation by cylinders.
BLK - (also BLKS and BLOCKS) Allocation by blocks (Note that the block size is specified in the OUTFILE_BLKSIZE command.)
KB - (also KILOBYTES) Allocation by Kilobytes for the ICF catalog environment only.
MB - (also MEGABYTES) Allocation by Megabytes for the ICF catalog environment only.
Note: Both the primary and secondary extents are allocated at 10 allocation units unless changed by the –VSAM_SPACE_PRIMARY or the –VSAM_SPACE_SECONDARY commands.
This command specification can be overridden at the data level by the VSAM_DATA_SPACE_TYPE command. At the data level, the corresponding cluster information is not recognized.
–OUTFILE_STORCLASS
Synonyms Include: –OUTSCLASS
This command pertains to DF/SMS allocation of new files when doing PKUNZIP processing. If you specify these classes, they will be passed to DF/SMS when data set allocation occurs.
–OUTFILE_STORCLASS(<SMS Storage Class>)
See IBM’s DF/SMS manuals for further information about this parameter.
225
–OUTFILE_UNIT
Synonyms Include: –OUTUNIT
For a newly extracted data set, the generic units for the output file can be specified using the OUTFILE_UNIT command.
–OUTFILE_UNIT(<units>)
unitname - An 8-character field specifying the name of the generic unit to which the output data set is to be allocated.
SYSDA - The default specification.
–OUTFILE_VOLUMES
Synonyms Include: –OUTVOL
For a newly extracted data set, the volume(s) is specified using the OUTFILE_VOLUMES command.
–OUTFILE_VOLUMES(<volname>[ <volname> <volname>…])
volname - A 217-byte field specifying the names of volume(s) (separated by blanks) onto which a newly extracted data set is allocated. There may be up to 31 volume names specified with this command.
For an output that is a new member of a new PDS, the first <volname> will only be used.
For a VSAM file, the volumes are specified at the Cluster Level.
–PAD_CHAR
Synonyms Include: –PAD
When extracting data into fixed length records, specify the pad character with the command PAD_CHAR. If the command is not specified and padding is needed, the default will be spaces (X‘40’) for TEXT and nulls (X’00’) for BINARY extraction.
–PAD_CHAR(<pad char>)
pad char - May be one of the following:
None - For –PAD_CHAR(), the space (X’40’) is used.
Any EBCDIC character.
Any Hexadecimal character with the format X(‘<hex character>’).
226
Multiple pad characters will be used if needed to fill in at the end of the record to make it the required fixed record length.
–PAD_VSAM
Synonyms Include: –PADVSAM, –NOPADVSAM
This command instructs the PKUNZIP program to pad variable length records with a character(s) specified by the PAD_CHAR command to the length specified in the VSAM_RECORDSIZE command (average and maximum lengths must be the same).
–PAD_VSAM(Y|N)
Y - YES - Records are padded with the pad character specified in PAD_CHAR. If the lengths specified in the VSAM_RECORDSIZE command are of different lengths, padding will not occur.
N - NO - Records are not padded.
PARMLIB_DSNAME_UNZIP
Synonyms Include: –UNZIPCONFIG
PARMLIB_DSNAME_UNZIP(<dataset>)
This setting is specified in the defaults module only.
data set - PKZIPz can be configured or customized to operate in a number of ways. The name of the data set containing the configuration specifications for UNZIP processing is specified by the use of this command. The default command for this data set is NULLFILE.
Note that some installations try to eliminate any allocation of a PARMLIB or CONFIG data set through PARMLIB_DSNAME_ZIP and PARMLIB_DSNAME_UNZIP.
If no installation-supplied data set commands are desired, then ACZDFLT parameters may be set to bypass the allocation attempt. Only //SYSIN DD and EXEC PARM='...' parameters will be processed.
PARMLIB_DSNAME_ZIP
Synonyms Include: –ZIPCONFIG
PARMLIB_DSNAME_ZIP(<dataset>)
This setting is specified in the defaults module only.
227
data set - PKZIPz can be configured or customized to operate in a number of ways. The name of the data set containing the configuration specifications for ZIP processing is specified by the use of this command. The default command for this data set is NULLFILE.
PARMLIB_FILE_WAIT_MAX
Synonyms Include: N/A
If the file indicated by PARMLIB_DSNAME_ZIP or PARMLIB_DSNAME_UNZIP is in use elsewhere and cannot be opened, the command PARMLIB_FILE_WAIT_MAX indicates the maximum amount of time PKZIPz will wait for the file to become available before abnormally ending the job. The default setting is five minutes.
PARMLIB_FILE_WAIT_MAX(<HHMMSSTH>)
This setting is specified in the defaults module only.
HHMMSSTH:
HH - Hours.
MM - Minutes.
SS - Seconds.
T - Tenths of a second.
H - Hundredths of a second.
00050000: 5 minutes is the default.
PARMLIB_FILE_WAIT_TIMER
Synonyms Include: N/A
If the file indicated by PARMLIB_DSNAME_ZIP or PARMLIB_DSNAME_UNZIP is in use elsewhere and cannot be opened, the command PARMLIB_FILE_WAIT_TIMER is the polling time used during the wait process. The default setting is five seconds.
PARMLIB_FILE_WAIT_TIMER(<HHMMSSTH>)
This setting is specified in the defaults module only.
HHMMSSTH:
HH - Hours.
MM - Minutes.
SS - Seconds.
T - Tenths of a second.
228
H - Hundredths of a second.
00000500: 5 seconds is the default.
–PASSWORD
Synonyms Include: –PASS, –PWD
To encrypt a ZIP archive file, the PASSWORD command is used to establish an associated encryption/decryption key for that file.
–PASSWORD(<userpw>)
userpw - Your selected passphrase, needed to encrypt or decrypt the ZIP archive file.
The passphrase:
Is case-sensitive - The following passwords are considered three different passwords: Password, PASSWORD, or password. If the password is being input from JCL, take note that the JCL editor may capitalize all the letters of the password.
Can be 1-250 characters in length and can include any characters that can be processed by the designated translation table TRANSLATE_TABLE_FILEINFO.
Processing Notes
If using embedded blanks in the passphrase, the keyword form of the command should not be used.
Special command control characters (such “|”) should not be used as a command value.
The passphrase value is not stored in the ZIP archive. As a result, care must be taken to keep the passphrase secure and accessible by another source. Different passphrases may be used for various files within a ZIP archive, although only one passphrase may be specified per run.
Passphase translation is done from EBCDIC to ASCII using the TRANSLATE_TABLE_FILEINFO. When cross-platform exchanges are done with encrypted archives, take care to use characters that will be acceptable to both platforms with the translate table in use.
–PATH
Synonyms Include: –NOPATH
The PATH command determines how an MVS filename is converted to a ZIP archive format.
229
–PATH(Y|N)
When Using –PATH(Y)
When converting a filename from MVS format to ZIP archive format, the PATH(Y) command is specified so that all of the data set levels are used in the archive name. PATH(Y) is the default.
Example:
Given the PDS member:
PROJECT.DEPT.SOURCE(TEST)
and a command of: –PATH(Y)
the ZIP internal filename will be:
PROJECT/DEPT/SOURCE/TEST
Example:
Given the PDS dataset that contains member
CLOCK00
SYS1.PARMLIB
and a command of: –PATH(Y)
the ZIP internal filename for that member will be:
SYS1/PARMLIB/CLOCK00
When Using –PATH(N)
When converting a filename from MVS format to ZIP archive format, the PATH(N) command is specified so that the last level of the data set is used as the archive name. This command is not used if a matching ZIPPED_DSN command exists.
Example:
Given the PDS member:
SYS1.PARMLIB(CLOCK00)
and a command of: –PATH(N)
the ZIP internal filename will be:
CLOCK00
–PKSUPPRC
Synonyms Include: N/A
PKSUPPRC is a non-default command that allows the return code to be suppressed for the following messages:
230
ZPAM092E – Nothing to do.
ZPAM093W – No files match; Initializing/Copying Archive.
ZPCM032W – Cataloged file request not found
ZPEX013W – Truncation.
ZPEX084E – Unsupported Compression Method
ZPEN002W – Encryption Method not supported by this release
ZPEN020W – Filename Encryption is being deactivated in the output archive
ZPEN016W – Strong decryption bypassed for PKZIP Standard Edition
ZPEN035E – Archive Authentication Failure
ZPEN039E – Archive Authentication unsuccessful (unsigned archive)
ZPEN045E – File Authentication Failure
ZPEN049E – Archive Authentication unsuccessful (unsigned file)
ZPEN057W – Certificate Validation Failed
–PRESERVE_CMD_SPACES
Synonyms Include: N/A
In releases of PKZIP 2.61 and prior, a " |" was required to identify a command continuation, a blank preceding the “ |” was needed to identify the continuation action. The support of continuation command records with embedded blanks that was added with PKZIP MVS Version 5 (for extended filenames) required all occurrences of " |" (preceding space) to be changed to "|".
–PRESERVE_CMD_SPACES
Y - YES - The default; required for the preservation of preceding spaces when required for specific command values—for example, UNIX-format file names with embedded blanks and ARCHIVE_COMMENT text.
N - NO - For backward-compatibility. Enables you to remove blanks preceding the "|" as in earlier releases of PKZIP MVS (provided with fix TT1053).
Warning: Space preservation for current and future commands is predicated on the default PRESERVE_CMD_SPACES=Y. Control cards should be converted to the PKZIPz format (no blanks preceding "|" for continued lines).
231
–PROCESS_ALIAS
Synonyms Include: –ALIASMEMBER, –NOALIASMEMBER
–PROCESS_ALIAS(Y|N)
During ZIP processing, the PROCESS_ALIAS(Y) command specifies that the alias entries for selected PDS members are to be retained for the real member. These stored attributes then may be used when extracting the file to a PDS.
During UNZIP processing, the PROCESS_ALIAS(Y) command specifies that saved alias entries for selected PDS members are to be restored to the PDS directoy in association with the real member.
Processing Notes
Alias members are not selectable as members or files from the archive. The “real” member must be selected.
SAVE_FILE_ATTRIBUTES(CENTRAL) must be active during the ZIP process for this command to take effect.
–RECALL_TO_ZIP
Synonyms Include: –RECALL, –NORECALL, –SELECT_MIGRATED
This command instructs PKZIPz to either recall a data set with DFHSM or to bypass that data set if a recall is required. This will speed up processing if migrated data sets are not required to be zipped. The catalog information is reviewed for volume serial (MIGRATE or ARCHIVE) to identify data sets which are migrated. (“ARCHIVE” is used by some non-IBM storage management products).
–RECALL_TO_ZIP(Y|N)
Y - YES - Recall a data set using DFHSM. Note that this specification may incur significant processing delays as DFHSM performs the recalls so that file attributes can be checked. File attributes must be checked to ensure that partition data set information is all specified and characterized before file selection can occur.
N - NO - Bypass recall of DFHSM data sets.
232
–RECIPIENT
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
Here you identify the Public-key recipients that are capable of decrypting the archive.
-RECIPIENT(certificate_store_type:selection[,R][,PASSWORD=password])
certificate_store_type: designates the media in which the certificate(s) containing the public keys are contained.
Certificate Store Type Selection
DD: A ddname pre-allocated to the job step.
FILE:
A dataset name that is to be dynamically allocated. This is a fully qualified name conforming to fopen() syntax.
DA: Converts MVS DSN to FILE:
DS: Converts MVS DSN to FILE:
DSN: Converts MVS DSN to FILE:
DB: Search criteria
LDAP: Search criteria
System: Search criteria
Direct File Access – DD, FILE, DA, DS, DSN
A data set reference may be made in the command to access the x.509 file representing the certificate and associated keys. The local certificate store index search (used for DB) is bypassed. This type of reference provides the means to specify a particular certificate/key set when a DB: search request may return more than one. The x.509 does not need to be installed to the local certificate store index. However, certificate validation policy settings may require access to supporting components of the local certificate store to complete certificate validation.
FILE: See the IBM C/C++ Optional Feature Bookshelf, Programming Guide, section “Using a Data Set Name” for fopen() for more information. MVS data set access (non-HFS/zFS) requires “//” as a prefix.
DA:, DS: and DSN: all imply that an MVS data set (or partitioned member) is being accessed. SecureZIP will automatically perform a conversion to the proper FILE: format for the file to be opened.
Search Criteria, Database
DB and LDAP Certificate Stores allow a search to be performed based on selected field types.
233
DB
The DB Store currently supports searching based on Email address (mail= or EM=), or Common Name (CN=). The value is resolved in a case-insensitive manner within the database index. However, the string must be an exact representation of the value as loaded by the certificate store administrator. Generic and masked searches are not supported.
Example:
If search criteria is "cn=joe smith" and "CN=JOE SMITH”
Will resolve to "Joe Smith”
If search criteria is "CN=J* Smith" and "CN=JoeSmith"
Will not resolve to "Joe Smith”
It is possible that more than one certificate may be returned for a single Common Name or Email search. If Joe Smith had 2 different certificates installed (from different sources, or the same source for different years) that have the same CN= or EM= value, then both certificates will be included in the recipient list.
A DB: search will not return entries marked by the certificate store administrator as “Suspended”. Entries may be marked this way because they are no longer considered valid for use in the installation.
LDAP
The LDAP Store provides support for Email, Common Name, and other searchable fields supported by your LDAP Service Provider. Up to 3 LDAP servers will be searched based upon the certificate store Configuration settings selected (see {LDAP:...}).
Once a valid certificate is returned for a search in a specified LDAP, the search for that RECIPIENT request is finalized. If a specific LDAP server does not return a valid certificate, then subsequent LDAP servers will be searched until a match is found or the list of configured LDAP servers is exhausted.
Example:
Recipient “A” In LDAP #1 and LDAP #2
Recipient “B” In LDAP #2
LDAP#1 & #2 available Recipient “A” retrieved from LDAP #1
Recipient “B” retrieved from LDAP #2
LDAP#1 not available Recipient “A” retrieved from LDAP #2
Recipient “B” retrieved from LDAP #2
Recipeint “A” cert invalid in LDAP#1
Recipient “A” retrieved from LDAP #2
Recipient “B” retrieved from LDAP #2
234
System
This option combines the search capabilities of "DB:" and "LDAP:" into one request. Within the definitions set for the certificate store Configuration, the local system "DB:" is searched first.
If one or more entries are determined to exist in the local DB: store, then those entries will be used.
If no entries can be located in the DB: store, then a subsequent search of the configured LDAP(s) will be performed according to the rules for LDAP.
If an error is encountered for a DB: certificate that is indexed in the DB: Store, the search is terminated (that is, no LDAP search is performed).
Please note that the CN= and EM= value formats must be compatible between the DB: and LDAP: search engines.
Example:
If DB contains CN=Joseph Smith
If LDAP contains CN=Joe Smith
Request SYSTEM:CN=
Action Can only satisfy one of the search types
Resolution Separate commands should be coded for each cert_store_type
[,R]
This is an optional flag indicating that one or more certificates must be satisfied from this RECIPIENT request. A ZIP run will terminate if one or more required recipients cannot be resolved.
When a certificate store cannot be opened for a RECIPIENT request that is not required, a non-zero return code may be issued to indicate that a complete search for the recipient could not be performed.
When one or more recipients are requested but none can be resolved, a ZIP run will be terminated regardless of the "R" (required) flag.
[,PASSWORD=]
This designates the password required to access a private-key certificate. This password must be supplied for the UNZIP/decryption of an archive encrypted using certificate-based encryption.
When a value is specified during ZIP/encryption processing, the target must be an X.509 PKCS#12 private-key certificate. This allows the Public key to be obtained from a private-key Certificate, thereby eliminating the need to store both public-key (PKCS#7) and private-key (PKCS#12) certificates for the same user.
The PASSWORD value may contain blanks and is delimited by the closing right parenthesis ")" of the RECIPIENT command. Quotes and apostrophes should not be used as start/end delimiters.
235
The PASSWORD parameter is not valid for LDAP searches.
Processing Notes
A “BSAFE” ENCRYPTION_METHOD must be active. However, SecureZIP will automatically switch to BSAFE mode when any of the AES algorithms are specified in combination with a RECIPIENT request for encryption.
When extracting data, SecureZIP will automatically switch to BSAFE mode for AES, 3DES and RC4 files. Exceptions to this are when PKZIP "Standard" encryption files are encountered, or ENCRYPTION_METHOD is explicitly set to one of the PKZIP AES algorithms via a command override.
An absolute maximum of 3,275 public-key recipient certificates can be reflected in the ZIP archive for an individual file. The maximum number of certificates may not be achievable when multiple certificates are returned by Database or LDAP searches. This is because multiple certificates may be returned for a single search request and the maximum number exceeded. The ZIP run will terminate if the maximum number is exceeded.
The total number of RECIPIENTs able to be reflected in the ZIP archive for an individual file is restricted by the file attributes also stored in the central directory for the file. SAVE_FILE_ATTRIBUTES=NONE may be set to increase the amount of space available to hold recipient information. However, if NONE is specified, the file will not be able to be restored to its original file format automatically by UNZIP processing.
A maximum number of RECIPIENT requests (including MASTER_RECIPIENT) is limited to 3,275. This is true even if the RECIPIENT requests do not result in public-key certificates being found.
It is important that the “PASSWORD=” keyword be coded in upper case. Any variation in case or misspelling will result in a public-key certificate access attempt (which will fail for a private-key PKCS#12 certificate).
RECIPIENT= may be specified in the defaults module (ACZDFLT or other user-designated module). Specification of this default value in combination with a default strong-security ENCRYPTION_METHOD will result in a corresponding RECIPIENT command being automatically entered to the ZIP run. (ENCRYPTION_METHOD specifies a strong-security profile when any value other than “Standard” or “NONE” is specified). This value cannot be overridden or nullified through standard command stream inputs. A proper LDAP or local certificate store configuration should also be supplied to ensure that the specified RECIPIENT certificate(s) will be found.
MASTER_RECIPIENT= may also be specified in the defaults module to provide a contingency key. The MASTER_RECIPIENT value is included in the processing stream when the conditions for default RECIPIENT processing are met AND either a PASSWORD or RECIPIENT value is present. In other words, MASTER_RECIPIENT is meant to be included when other strong security activation (encryption) takes place.
Passwords will be masked out in SYSPRINT output displays.
When FILE: is specified as the certificate lookup type, the data set name will be treated in accordance with fopen() as documented in the IBM C/C++ Programming Guide. See “Performing OS I/O Operations - Using a Data Set Name”. Starting a filename with "//" indicates the file refers to a non-POSIX file or data set. The name specified is translated to upper case by the run-time environment.
236
Using VERBOSE when recipients are active will display the certificate store configuration (ZPCM023I) and a report of which recipient types are being requested (ZPCM024I).
LDAP "best fit" selection (see the LDAP_ENCRYPT_CERT_SELECT command) can limit the total number of LDAP certificates returned. Otherwise, all certificates meeting the base address/name selection request are included.
Certificates that are used for processing are subject to validation policy settings as governed by {VALENCRYPT}. The policy settings are defined by the certificate store administrator. If no VALENCRYPT settings are found by SECZIP (either through the certificate store Profile or commands), then all aspects of certificate validation will be attempted by default.
–RECURSE_LEVELS
Synonyms Include: –RECURSE, –NORECURSE
During ZIP file selection with masking, this specifies whether or not to use file names represented by wildcard specifications.
-RECURSE_LEVELS(Y|N)
When Specifying Y (YES)
Additional data set levels below the qualifiers specified are included in the match for a user specified data set.
Example:
For the selection: XXX.YYY(*)
and a command of: -RECURSE_LEVELS(Y)
the following datasets would be found:
XXX.YYY
XXX.YYY.ZZZ
XXX.YYY.REF
XXX.YYY.Z12
or
237
Example:
For the selection: PAYROLL.DEPT(*)
and a command of: -RECURSE_LEVELS(Y)
the following datasets would be found:
PAYROLL.DEPT.ENG
PAYROLL.DEPT.ACC05
PAYROLL.DEPT.MKT
PAYROLL.DEPT.ADVERT
When Specifying N (NO)
Only the specified data set levels from your file selection are used in the match for file selection.
Example:
For the selection: XXX.YYY(*)
and a command of: -RECURSE_LEVELS(N)
the only dataset found would be:
XXX.YYY
and would not be: XXX.YYY.ZZZ
XXX.YYY.REF
XXX.YYY.Z12
or
Example:
For the selection: PAYROLL.DEPT(*)
and a command of: -RECURSE_LEVELS(N)
the only dataset found would be:
PAYROLL.DEPT
and would not be: PAYROLL.DEPT.ENG
PAYROLL.DEPT.ACC05
PAYROLL.DEPT.MKT
PAYROLL.DEPT.ADVERT
–SAVE_FILE_ATTRIBUTES
Synonyms Include: –ATTRIBCENTRAL, –ATTRIBLOCAL, –ATTRIB, NOATTRIB, USE_FILE_ATTRIBUTES
- Cross Platform Compatible command (iSeries, and OS/400).
238
The SAVE_FILE_ATTRIBUTES command specifies whether and where to save the attributes of this compressed file.
–SAVE_FILE_ATTRIBUTES(CENTRAL|LOCAL|BOTH|NONE|NO|N)
In PKZIP Processing
CENTRAL - Allocation attributes for the ZIPPED file are stored in the central directory. PKZIPz uses this information when extracting a file.
Note: The –OUTFILE series of commands may be used during PKUNZIP processing to ignore stored attributes.
LOCAL - Attributes for the ZIP file are stored (only) in the local Directory. PKZIPz does not use the local Directory when extracting a file.
BOTH - The attributes for a compressed file are to be stored in the ZIP archive in both the Central and the local Directories of an archive when the BOTH modifier is issued.
NONE|NO|N - The attributes for a compressed file are not to be stored in the ZIP archive. This is useful when the archive is to be sent to another platform where the allocation information is not referenced. It also serves to reduce the size of the archive.
In PKUNZIP Processing
NONE|NO|N - The attributes for a ZIP file should not be used when creating a new extracted data set. Instead, the OUTFILE series of commands may specify attributes for the new extracted data set. Any other value will cause PKZIPz to blend the extended attributes saved in the archive with override commands for new dynamically allocated files.
The attributes are not used when an OUTFILE_DDNAME JCL allocation is used. The user should specify all appropriate values through JCL or pre-allocation.
–SAVE_LRECL
Synonyms Include: –RDW, –USE_SAVED_LRECL, –ZDW
- This command is not compatible with UNIX, iSeries, OS/400, and Windows.
This command is used in combination with DATA_TYPE(BINARY) during ZIP processing to specify record lengths should be retained with the ZIPPED file. This is particularly useful for files containing variable-length records that need to be restored to their original length during UnZip processing.
–SAVE_LRECL(Y|N)
Y - YES - Specifies that record length information is to be included in the Zip archive.
N - NO - Specifies that record length information is not to be included.
239
A VIEWDETAIL will show “File Type: BINARY SAVED_LRECL (RDW)” when a file has been zipped with this option.
It is highly recommended that VSAM files ZIPPED as BINARY should have SAVE_LRECL(Y) specified even if the catalog indicates the average and maximum recordsize to be the same. This is not a guarantee that all records in the VSAM CLUSTER are of the same length.
SAVE_LRECL(Y) should always be specified with Load modules.
It may be the case that a particular platform does not support the SAVE_LRECL command and does not use stored record lengths in a binary file and therefore the file should be processed as straight DATA_TYPE(BINARY) , otherwise formatting problems may be encountered with the data.
This command does not apply to files ZIPPED as TEXT.
The command USE_SAVED_LRECL=Y retained for backward compatibility, but is not required when the SAVE_LRECL=Y was specified with the ZIP because the archive contains the required information. This command should not be set to “Y” for extraction if the file was not saved with it on.
Usage Notes
The length field that this command includes in the archive is not an IBM RDW but a ZIP internal length value. The format of this value is described in the PKWARE Application Note (AppNote), which defines the .ZIP file format specification. The AppNote is available in the Developer section of the PKWARE Web site. Bit 0x0002 is on in the Internal File Attributes flag of the Central Directory record to indicate that this length control field is used. The field is stored in little-endian format.
–SECURE_OPT_MSK3DES
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
-SECURE_OPT_MSK3DES(Y|N)
The purpose of this switch is to maintain compatibility with Windows (pre-XP) systems where the private key certificate was not imported with "Mark the private key as exportable". This has importance when sharing AES-encrypted files with recipients.
Y - YES - Instructs SecureZIP to use 3DES (168-bit) encryption for key-generation material when any AES algorithm is specified for ENCRYPTION_METHOD. This provides greater flexibility for exchanging archives with non-XP Windows systems. However, the total security of the file may be reduced.
N - NO - Instructs SecureZIP to use the same algorithm to protect key-generation material as is specified for the data with ENCRYPTION_METHOD. This is a preferred setting to maximize security.
240
SECUREZIP_CONFIG
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
SECUREZIP_CONFIG=dataset(member)
This setting is specified in the defaults module only.
This setting specifies a PDS[E] member that contains SecureZIP certificate store configuration commands to be automatically included in the processing stream. The configuration command values from this member will be included at the start of command input processing prior to //SYSIN statements being read. The data set(member) will be converted into an "INCLUDE_CMD=(pds[e](member)" command internally and will be echoed to the message log in accordance with the ECHO setting.
SecureZIP certificate store Configuration commands entered from other sources such as //SYSIN will override the values read in from this source.
–SELECT_CATALOGED_ALIAS
Synonyms Include: –ALIAS_NAME, –NOALIAS_NAME, –SELECT_DSN_ALIAS
This parameter specifies whether ALIAS catalog entries are to be eligible for processing when performing a ZIP request for ACTION(ADD) or ACTION(UPDATE).
–SELECT_CATALOGED_ALIAS(Y|N)
Y - YES - Alias catalog entries are processed
N - NO - alias catalog entries are not processed
This command specifies that if there is a data set named XYZ that has an alias defined as ABC, PKZIPz processing will zip the XYZ data set if ABC is requested. It is an alternative way of asking for files.
241
–SELECT_FROM_PDS
Synonyms Include: –PDS_TARGET, –ZIPCUR
Used In PKZIP Processing
The SELECT_FROM_PDS command is used as a shortcut to specify the current higher level components which would apply to the files that follow in the command list. It eliminates having to enter the higher level data set components each time a different data set is referenced.
–SELECT_FROM_PDS(<PDS name>)
Example:
Zipping: ABC
with commands of: –SELECT_FROM_PDS(DOG.PONY.SHOW)
ABC
will select the file for zipping:
DOG.PONY.SHOW(ABC)
Used In PKUNZIP Processing
The SELECT_FROM_PDS command is used to designate an output library for files to be extracted into. It is commonly used when a PDS is not specified in a data set name, for example, the name levels were dropped by the HIERARCHY(N) command during ZIP processing when the archive was created.
–SELECT_FROM_PDS (<PDS name>)
Example:
Unzipping: ABC
with a command of: –SELECT_FROM_PDS (DOG.PONY.SHOW)
will extract the PDS member:
DOG.PONY.SHOW(ABC)
See UNZIPPED_DSN to specify high level qualifiers in a more general fashion.
242
–SELECT_TAPE
Synonyms Include: –NOTAPE
This command specifies whether tape files are to be processed when requesting data sets for ZIP processing via the catalog.
–SELECT_TAPE(Y|N)
Y - YES - All tape files in the catalog will be processed.
N - NO - Tape files will be filtered out during processing of the catalog.
See also: SELECT_VSAM, SELECT_MIGRATED, and SELECT_GDGALL.
–SET_ERROR_RC
Synonyms Include: N/A
The SET_ERROR_RC may be used to set a firm return code when an error has been detected. Internal return codes of 8 or above will be converted to this value. This optional feature may be of use to installations converting from PKZIP for MVS 2.x, which uses RC=24 for severe errors.
–SET_ERROR_RC(<nbr>)
nbr - Return code to be passed to the system.
–SHOW_SETTINGS
Synonyms Include: –SS
This command causes current command settings to be displayed in the output at the point in the input that the SHOW_SETTINGS command is invoked. Since command settings may come from the Execute Parm, the Parmlib Configuration File, or from SYSIN, the use of the SHOW_SETTINGS command is useful in showing the combined effect of all sources leading up to the request.
–SHOW_SETTINGS
No parameter is required.
243
Some SecureZIP command settings are purposely removed from this display. Other information is available in the listing for commands such as:
AUTHCHK
PASSWORD
MASTER_RECIPIENT
RECIPIENT
SIGN_ARCHIVE
SIGN_FILES
Note: This command does not override or interrupt the processing request in effect for the run(–ACTION). If a standalone report is desired without attempting ZIP/UNZIP archive processing, use the command sequence “–SS –PATCH_REPORT”.
–SIGN_ARCHIVE
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
Here you identify the private-key certificate that is to be used to digitally sign the archive’s central directory. One and only one certificate may be used to perform this operation. Signing an archive by signing its central directory enables people who receive the archive to confirm that the archive as a whole is not changed. By contrast, signing only individual files in an archive enables people to confirm that the particular signed files are unchanged but not that the archive has had files added or removed.
-SIGN_ARCHIVE(certificate_store_type:selection,PASSWORD=password)
certificate_store_type:selection - Designates the media containing the certificate(s) with the private key.
Certificate Store Type Selection
DD: A ddname pre-allocated to the job step.
FILE:
A dataset name that is to be dynamically allocated. This is a fully qualified name conforming to fopen() syntax.
DA: Converts MVS DSN to FILE:
DS: Converts MVS DSN to FILE:
DSN: Converts MVS DSN to FILE:
DB: Search criteria
244
Direct File Access – DD, FILE, DA, DS, DSN
A data set reference may be made in the command to access the x.509 file representing the certificate and associated keys. The local certificate store index search (used for DB) is bypassed. This type of reference provides the means to specify a specific certificate/key set when more than one may be returned by a DB: search request. The x.509 does not need to be installed to the local certificate store index. However, certificate validation policy settings may require access to supporting components of the local certificate store to complete certificate validation.
FILE: See the IBM C/C++ Optional Feature Bookshelf, Programming Guide, section “Using a Data Set Name” for fopen() for more information. MVS data set access (non-HFS/zFS) requires “//” as a prefix.
DA:, DS: and DSN: all imply that an MVS data set (or partitioned member) is being accessed. SecureZIP will automatically perform a conversion to the proper FILE: format for the file to be opened.
Search Criteria, Database
DB reflects the local certificate store, thereby allowing a search to be performed based on selected field types.
DB
The DB Store currently supports searching based on email address (mail= or EM=), or common name (CN=). The value is resolved in a case-insensitive manner within the database index. However, the string must be an exact representation of the value as loaded by the certificate store administrator. Generic and masked searches are not supported.
A DB: search will not return entries marked by the certificate store administrator as “Suspended”. Entries may be marked this way because they are no longer considered valid for use in the installation.
Example:
If search criteria is "cn=joe smith" and "CN=JOE SMITH”
Will resolve to "Joe Smith”
If search criteria is "CN=J* Smith" and "CN=JoeSmith"
Will not resolve to "Joe Smith”
Because it is possible that more than one certificate may be returned for a single common name or email search, care should be taken to ensure that unique names and or passwords be used when installing the private-key certificates to the database. Since only one certificate may be used for SIGN_ARCHIVE, another alternative is to specify one of the FILE formats to selecte a specific certificate instead of using the DB form of the command.
,PASSWORD= - The password required to access a private key. When a value is specified, the target must be an X.509 PKCS#12 private-key certificate.
The PASSWORD value may contain blanks and is delimited by the closing right parenthesis ")" of the signing command. Quotes and apostrophes should not be used as start/end delimiters.
245
Processing Notes
This command has no effect on an archive that contains 0 files (for example, an archive that has had all its files deleted). An attempt to sign a logically empty archive results in an unsigned archive, and an informational message is logged.
Signing the archive central directory also signs the archive’s file statistics and ZIP control information such as the 32-bit CRC. This provides some added protection for files because data tampering would surface as a CRC-check during a TEST or EXTRACT operation.
Note that even signing the central directory of an archive does not sign archive comments. Archive comments should not be considered authenticated even if an archive is signed. Do not rely on archive comments for sensitive information.
The processor requirements and elapsed time associated with signing the archive central directory is proportional to the size of the directory (normally a function of the number of files in the archive together with the amount of SAVE_FILE_ATTRIBUTES information associated with each). Typically the central directory is small compared with the size of file data, and only one signing operation is performed for SIGN_ARCHIVE regardless of the number of files.
It is important that the PASSWORD= keyword be coded in upper case. Any variation in case or misspelling will result in a public-key certificate access attempt (which will fail for a private-key PKCS#12 certificate).
SIGN_ARCHIVE= should not be specified in the defaults module (ACZDFLT or other user-designated module). This is because specification of the command necessitates the inclusion of a clear text password. A better technique is to use INCLUDE_CMD and reference an independent file from which the SIGN_ARCHIVE command may be read (and file-protected from read access by the system’s security facility).
Passwords are masked out in SYSPRINT output displays.
When FILE: is specified as the certificate lookup type, the data set name will be treated in accordance with fopen() as documented in the IBM C/C++ Programming Guide. See “Performing OS I/O Operations - Using a Data Set Name”. Starting a filename with “//” indicates the file refers to a non-POSIX file or data set. The name specified is translated to upper case by the run-time environment.
A local certificate store configuration is required to complete the processing of this command. Even when a direct FILE specification is made to locate the private-key certificate, the {CSCA=} and {CSROOT=} certificate store components must be accessible to complete the certificate signing chain within the archive. This information is required to complete authentication processing on the target system when the local certificate store on that system does not contain the certificate authority chain required to validate TRUST.
Processing will be terminated if the requested certificate cannot be accessed.
Certificates that are used for processing are subject to validation policy settings as governed by {VALSIGN}. The policy settings are defined by the certificate store administrator. If no VALSIGN settings are found by SECZIP (either through the certificate store profile or commands), then all aspects of certificate validation will be attempted by default.
Signed archives are tolerated by prior releases of PKZIP/SecureZIP for z/OS but are not processed for authentication.
246
–SIGN_FILES
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
Here you identify the private-key certificate that is to be used to digitally sign files to be added to the archive. Multiple signing certificates may be applied to the files. Signing an archive by signing its central directory enables people who receive the archive to confirm that the archive as a whole is not changed. By contrast, signing only individual files in an archive enables people to confirm that the particular signed files are unchanged but leaves open the possibility that the archive has had files added or removed.
-SIGN_FILES(certificate_store_type:selection[,R],PASSWORD=password)
certificate_store_type:selection - Designates the media in which the certificate(s) containing the private key is contained.
See SIGN_ARCHIVE for a discussion of the certificate store types and selection processing.
It is possible that more than one certificate may be returned for a single common name or email search. As a result, each one matching the specified password will be used to sign the file(s).
[,R] - an optional flag indicating that one or more certificates must be satisfied from this signing request. A ZIP run will terminate if the required certificates cannot be resolved.
When a certificate store cannot be opened for a SIGN_FILES request that is not required, a non-zero return code may be issued to indicate that a complete search for the recipient could not be performed.
When one or more signers are requested but none can be resolved, a ZIP run will be terminated regardless of the "R" (required) flag.
,PASSWORD= - This designates the password that is required for a private-key certificate. When a value is specified, the target must be an X.509 PKCS#12 private-key certificate.
The PASSWORD value may contain blanks and is delimited by the closing right parenthesis ")" of the signing command. Quotes and apostrophes should not be used as start/end delimiters.
Processing Notes
A NULL file (a binary file having 0 bytes of data) will be signed. However, note that the digital signature is based on a fixed hash value.
The entire data stream of each file is run through the hash algorithm before compression or encryption. However, file text data is translated before hashing so that the receiving system is able to hash the identical stream after decryption/decompression.
The processor requirement for a file signature is directly related to the size of the file(s) being signed and/or authenticated (see SIGN_HASHALG). Therefore, when processing costs are a consideration, the decision whether to use SIGN_FILES to sign large files should be based on
247
the business case. Sometimes SIGN_ARCHIVE may be more appropriate. (The directory size is proportional to the number of files in the archive, not the physical size of the file data.)
A separate signing operation is performed for each supplied certificate, for each file. Processor and elapsed time will be impacted in proportion to the number of signatories and files selected.
The number of file signatures that can be held for each file is constrained by a number of factors. These include SAVE_FILE_ATTRIBUTES=Y, the size of the signatures generated (based on the size of the certificate information), the number of certificates in the authenticating certificate authority chain, the number of different certificate authorities used in association with the signing certificates, whether FILENAME_ENCRYPTION=N, and the number of RECIPIENTs for certificate-based encryption of files. Typical ZIP operations support up to ten file signatories as a rule, although more or fewer may be achieved in practice.
It is important that the PASSWORD= keyword be coded in upper case. Any variation in case or misspelling will result in a public-key certificate access attempt (which will fail for a private-key PKCS#12 certificate).
SIGN_FILES= should not be specified in the defaults module (ACZDFLT or other user-designated module). This is because specification of the command necessitates the inclusion of a clear text password. A preferable technique is to use INCLUDE_CMD and reference an independent file from which the SIGN_FILES command(s) may be read (and file-protected from read access by the system’s security facility).
Passwords are masked out in SYSPRINT output displays.
When FILE: is specified as the certificate lookup type, the data set name will be treated in accordance with fopen() as documented in the IBM C/C++ Programming Guide. See “Performing OS I/O Operations - Using a Data Set Name”. Starting a filename with "//" indicates the file refers to a non-POSIX file or data set. The name specified is translated to upper case by the run-time environment.
A local certificate store configuration is required to complete the processing of this command. Even when a direct FILE specification is made to locate the private-key certificate, the {CSCA=} and {CSROOT=} certificate store components must be accessible to complete the certificate signing chain within the archive. This information is required to complete authentication processing on the target system when the local certificate store on that system does not contain the certificate authority chain required to validate TRUST.
Processing is terminated if none of the requested certificates can be accessed, regardless of the “R” required flag. If multiple requests are made and at least one signature is found, processing will continue normally.
Certificates used for processing are subject to validation policy settings as governed by {VALSIGN}. The policy settings are defined by the certificate store administrator. If no VALSIGN settings are found by SECZIP (either through the certificate store profile or commands), then all aspects of certificate validation will be attempted by default.
Signed Files are tolerated by prior releases of PKZIP/SecureZIP for z/OS but are not processed for authentication.
248
–SIGN_HASHALG
Synonyms Include: N/A
Requires SecureZIP Enterprise Edition
Here you specify the hashing algorithm that is used to generate a digital signature. It applies to the active SIGN_ARCHIVE and SIGN_FILES commands during a ZIP run.
–SIGN_HASHALG(SHA-1|MD5)
SHA-1 - The default algorithm generates a 20-byte hash value. This algorithm is supported by all SecureZIP products.
The information below is from FIPS 180-1:
This Standard specifies a Secure Hash Algorithm, SHA-1, for computing a condensed representation of a message or a data file. When a message of any length < 264 bits is input, the SHA-1 produces a 160-bit output called a message digest. The message digest can then be input to the Digital Signature Algorithm (DSA) which generates or verifies the signature for the message. Signing the message digest rather than the message often improves the efficiency of the process because the message digest is usually much smaller in size than the message. The same hash algorithm must be used by the verifier of a digital signature as was used by the creator of the digital signature.
The SHA-1 is called secure because it is computationally infeasible to find a message which corresponds to a given message digest, or to find two different messages which produce the same message digest. Any change to a message in transit will, with very high probability, result in a different message digest, and the signature will fail to verify.
MD5 - This algorithm generates a 16-byte hash value. It is included for compatibility with older releases of PKZIP on other platforms, which previously supported this algorithm.
Processing Notes
The entire data stream (archive central directory or file data) is run through the hash algorithm before compression or encryption. However, file text data is translated before hashing so that the receiving system is able to hash the identical stream after decryption/decompression.
During authentication operatings, SecureZIP for z/OS will dynamically detect which algorithms had been used for signing and perform the necessary processing to validate the signature.
249
–SIGNAL_ZIP64
Synonyms Include: N/A
Here you specify the severity of message and return code when creating or updating an archive and ZIP64 processing is required.
–SIGNAL_ZIP64(0|4|8)
0 - The default setting is to allow processing to continue with no effect on return code, and to issue informational message ZPAM046I.
4 - A setting to allow processing to continue with a minimal return code of 4, and to issue warning message ZPAM046W.
8 - The default setting is to halt processing with a return code of 8, and to issue error message ZPAM046E.
This feature may be of value when creating archives intended for distribution to systems that may not be able to handle the ZIP64 processing attributes. This may be due to the UNZIP software being used on the target system or the file system for the related OS. (For example, some UNIX or Windows FAT file systems cannot handle file sizes greater than 4 gigabytes).
Triggers for this command include:
More than 65,535 files are being placed into the archive
One or more source files are greater than 4 gigabytes in size
The amount of data written to the archive exceeds 4 gigabytes
Note: SIGNAL_ZIP64 is only available for use with an appropriately licensed product.
–SIMULATE
Synonyms Include: N/A
This command runs file selection processes for ACTION(ADD), ACTION(EXTRACT), ACTION(FRESHEN), and ACTION(UPDATE), but does not perform actual data manipulations for the files selected or for the output archive. Compression and Decompression algorithms will be bypassed. The input archive will be opened and read for directory information. STAGE_TAPE_ON_DISK will also be acted upon when specified or required.
–SIMULATE(Y|N)
Y - YES - Simulation of the file selection processes will occur.
N - NO - Full processing file processing will occur.
Note: This command is helpful when learning to code the ZIPPED_DSN and UNZIPPED_DSN commands.
250
–SNAP_SYSOUT_CLASS
Synonyms Include: N/A
This command specifies the SYSOUT class to be used for SNAP dumps. This feature is used only in conjunction with diagnostic features of PKZIPz and may not necessarily be used by an end user of the product.
–SNAP_SYSOUT_CLASS(<class>)
class - A one-character class assigned for the output of a SNAP dump.
* - The default.
–STAGE_TAPE_ON_DISK
Synonyms Include: –STAGE_TAPE_TO_DISK
This command specifies that input from a sequential device be stored in a temporary data set.
–STAGE_TAPE_ON_DISK(Y|N)
Y - Yes - Processing occurs on disk rather than on tape.
N - No - Processing occurs on tape, thus incurring significant processing degradation.
When reading a cartridge-based archive, the input can be stored in a temporary data set with the STAGE_TAPE_ON_DISK command. This occurs automatically when reading a 3420 (reel-to-reel) archive.
Should allocated temporary space be insufficient, the temporary data set is not used and processing continues with the tape. Note that this will have an impact on elapsed processing time.
It is helpful to include FREE=CLOSE in the DD statement in the JCL. This frees up the tape once the copy of the data has been made. If it is not included, the tape must remain mounted for the duration of ZIP processing.
Warning: If an //ARCHTEMP DD is found in the JCL, it will be over-written with the input archive. This DDNAME should not be used in a SecureZIP for z/OS job-step for any other purpose.
–STRIP_CHAR
Synonyms Include: –STRIP
This command specifies an ending character to be removed from the end of each record before it is compressed. There is no default as this process does not occur unless specified.
251
-STRIP_CHAR(<strip char>)
strip char - A single entry for the character(s) to be removed from the end of each record before compressing. One of three types may be entered:
No character specifies that trailing spaces (hex ’40’) are removed from every record.
Any EBCDIC character.
Any Hexadecimal character in the format: STRIP_CHAR(X’7B’).
If multiple characters occur at the end of the record, all occurrences of the character are removed.
Use caution with this command as it modifies the data set.
–SUPPRESS_DYNALLOC_MSGS
Synonyms Include: –NODYNMSGS
This command specifies that the dynamic allocation messages that appear in the job log be suppressed. This will not affect severe errors.
–SUPPRESS_DYNALLOC_MSGS
PKZIPz performs dynamic allocation requests for various files (archive, parameter, input, output, and temporary). During the system-service requests, the operating system may attempt to issue messages to the joblog or foreground TSO session screen. These messages are classified by level, ranging from Informational to error conditions. PKZIPz intercepts many of the dynamic allocation return code conditions and provides its own reporting according to the data set request being performed.
SUPPRESS_DYNALLOC is the default, which limits the operating system to reporting “Error” conditions (as the operating system defines “error”).
If additional dynamic allocation information is needed for problem determination purposes, the PKZIPz technical support staff will provide additional commands that will provide tracing of dynamic allocation activities.
Note: An ACZDFLT setting of –TRACE_DYNALLOC=0 can be used to make this the default.
–SYSPRINT_DCB
Synonyms Include: N/A
This command can only be entered through a defaults module (see ACZDFLT) or as an EXEC parameter. The SYSPRINT DCB attributes can be customized.
252
–SYSPRINT_DCB(FB132|FBA121|FBA133|FA121)
FB132 - SYSPRINT DCB attributes will be fixed block 132 no ASA.
FBA121 - SYSPRINT DCB attributes will be fixed block 121 with ASA.
FBA133 - SYSPRINT DCB attributes will be fixed block 133 with ASA.
FA121 - SYSPRINT DCB attributes will be fixed 121 with ASA.
The ASA control character (character in column 1) will be a blank.
SYSPRINT_SYSOUT_CLASS
Synonyms Include: N/A
This command specifies the SYSOUT class to be used for SYSPRINT messages when a SYSPRINT allocation is not provided for the job/session.
SYSPRINT_SYSOUT_CLASS(<class>)
This setting is specified in the defaults module only.
class - A one-character class assigned for the output of a SYSPRINT listings.
The default is the JCL MSGCLASS associated with the runtime environment.
Record Length: 132.
Format: FB.
–TEMP_BLKSIZE
Synonyms Include: –TEMPBLKSIZ
This command specifies the block size of a temporary PKZIPz data set.
–TEMP_BLKSIZE(DYNAMIC|SMS|value)
DYNAMIC/SMS - A dynamically computed value will be requested by PKZIPz (although SMS or allocation routines in the operating system may override the value).
Value - A blocksize value; recommended to be sized at half-track for the selected TEMP_UNIT.
When either DYNAMIC or SMS is specified, a dynamically computed value will be requested by PKZIPz (although SMS or allocation routines in the operating system may override the value).
253
–TEMP_DATACLASS
Synonyms Include: –TEMPDCLASS
–TEMP_DATACLASS(<data class>)
Use this command to specify or override value for temporary work File allocation requests in a DF/SMS - controlled environment.
data class - Specifies the DF/SMS data class receiving the temporary ZIP data set.
See IBM’s DF/SMS manuals for further information about this parameter.
–TEMP_MGMTCLASS
Synonyms Include: N/A
–TEMP_MGMTCLASS(<mgmt class>)
Use this command to specify or override value for temporary work File allocation requests in a DF/SMS - controlled environment.
mgmt class - Specifies the DF/SMS management class receiving the temporary ZIP data set.
See IBM’s DF/SMS manuals for further information about this parameter.
–TEMP_RECFM
Synonyms Include: –TEMPTYPE
–TEMP_RECFM(U|F|FB)
The command specifies the record format of a temporary work data set.
U - Undefined record format.
F - Fixed record format.
FB - Fixed block record format.
254
–TEMP_SPACE_MULTIVOL
Synonyms Include: N/A
Control whether the dynamic allocation of a new non-VSAM temporary data set will request multiple volumes when TEMP_DATACLASS is not in effect.
–TEMP_SPACE_MULTIVOL=Y|N
N - When a value of “N” is specified, or an TEMP_DATACLASS is specified, SecureZIP does not provide a volume count in the dynamic allocation request. When multiple volumes are required to hold the temporary data set under this condition, the operating system may reject the volume extension with an associated IEC032I-04 E37 error.
Y - When “Y” is specified without an TEMP_DATACLASS, a maximum of 59 volumes will be requested in the DYNALLOC request. When this option is enabled, the catalog will show the archive data set as being a multi-volume data set.
The message IGD17271I Allocation has been allowed to proceed for data set may appear in the JOB log from the system, but will not affect SECZIP processing.
Note: See the SecureZIP for z/OS System Administrator’s Guide for more information on SMS dataclass considerations. See also the section “Large File Considerations” in Chapter 8 for discussions regarding SMS class controls of extended size data sets.
–TEMP_SPACE_PRIMARY
Synonyms Include: –TEMPPRI, –TEMPPRIMARY
–TEMP_SPACE_PRIMARY(<allocation units>)
allocation units - Specifies the number of allocation units for the primary extent of the temporary ZIP data set.
Default is the same as ARCHIVE_SPACE_PRIMARY.
–TEMP_SPACE_SECONDARY
Synonyms Include: –TEMPSEC, –TEMPSECONDARY
–TEMP_SPACE_SECONDARY(<allocation units>)
allocation units - The size of the secondary extent in allocation units for the temporary ZIP data set
Default is the same as ARCHIVE_SPACE_SECONDARY.
255
–TEMP_SPACE_TYPE
Synonyms Include: –TEMPSPACE
-TEMP_SPACE_TYPE(TRK|CYL|BLK)
TRK - Tracks
CYL - Cylinders
BLK - Blocks (with the size specified in the TEMP_BLKSIZE command)
–TEMP_STORCLASS
Synonyms Include: –TEMPSCLASS
-TEMP_STORCLASS(<storclass>)
Use this command to specify or override value for temporary work File allocation requests in a DF/SMS - controlled environment.
storclass - The DF/SMS storage class requested in placing the temporary ZIP data set. An installation’s DF/SMS ACS routine may reset the value.
See IBM’s DF/SMS manuals for further information about this parameter.
–TEMP_UNIT
Synonyms Include: –TEMPUNIT
-TEMP_UNIT(<unit name>)
unit name - Specifies the generic unit name indicating where the data set is to be allocated. SYSDA is the default if not provided.
Use the SHOW_SETTINGS command to determine the installation’s selected default values.
Note: The defaults may not reflect the installation values by the product installer.
256
–TEMP_VOLUMES
Synonyms Include: –TEMPVOL
-TEMP_VOLUME(<volname>[ <volname> <volname> …..]
volname - Specifies 1 to 31 volumes that indicate where the temporary ZIP data set is to be allocated. Separate multiple <volume name>s by spaces.
This command is used in conjunction with TEMP_UNIT to direct work files to a specific location. PKZIPz will use values specified in its dynamic allocation request. The installation’s storage management controls may redirect the actual file location.
Note: The defaults may not reflect the installation values by the product installer.
–TRACE_TABLE_SIZE
Synonyms Include: N/A
This command specifies the size of the internal trace table.
–TRACE_TABLE_SIZE(<tabsize>)
tabsize - An 8-byte field containing the size of the trace table.
–TRANSLATE_TABLE_DATA
Synonyms Include: –TRAN
- Cross Platform Compatible command (iSeries, OS/400, UNIX, and Windows).
–TRANSLATE_TABLE_DATA(<translation table name>)
Used In PKZIP Processing
Use the TRANSLATE_TABLE_DATA command to identify a particular translation table to be used when converting text file data from one character set to another. This command would be used, for example, when converting a file from EBCDIC to ASCII, which is the standard the ZIP archive text format.
Where <translation table name> specifies a useable table name for translation. EBC#8859 is the default if TRANSLATE_TABLE_DATA is not specified. the table specified in the defaults module and it can be changed by customizing the ACZDFLT module.
257
Used In PKUNZIP Processing
Use the TRANSLATE_TABLE_DATA command to identify a particular translation table to be used when extracting a text file from ASCII to anther character set. This command would be used, for example, when converting a ZIP archive file in ASCII to a non-MVS format of EBCDIC.
TRANSLATE_TABLE_DATA(<translation table name>) where <translation table name> specifies a useable table name for translation.
EBC#8859 is the default if TRANSLATE_TABLE_DATA is not specified. The default table selection may be changed to a different table.
PKZIPz provides certain “ready to use” translation tables commonly used in an OS/390 environment. These tables are provided “as is” and are not supported as part of PKZIPz. It is your responsibility to ensure that data translation mapping satisfies their requirements. More information can be found in the FAQ at http://www.pkware.com.
Language EBCDIC Code Page
ASCII Code Page
EURO/ASCII Code Page
EBCDIC Code Set ID
ASCII Code Set ID
EURO/ ASCII CODE Set ID
Table Name ASCII
Table Name EURO
German 273 850 858 EB AA AI TRTEBAA TRTEBAI
Spanish 284 850 858 EJ AA AI TRTEJAA TRTEJAI
Portuguese 282 850 858 EI AA AI TRTEIAA TRTEIAI
Italian 280 850 858 EG AA AI TRTEGAA TRTEGAI
Danish 277 850 858 EE AA AI TRTEEAA TRTEEAI
Norwegian 277 850 858 EE AA AI TRTEEAA TRTEEAI
Swedish 278 850 858 EF AA AI TRTEFAA TRTEFAI
Finnish 278 850 858 EF AA AI TRTEFAA TRTEFAI
French 297 850 858 EM AA AI TRTEMAA TRTEMAI
English UNIX
IBM 1047
ISO 8859-1
EBC#8859
English PC IBM 1047
IBM 850
EBC#850
–TRANSLATE_TABLE_FILEINFO
Synonyms Include: –FTRAN, –TRANSLATE_FILEINFO, TRANSLATE_FILENAME
- Cross Platform Compatible command (iSeries, OS/400, UNIX, and Windows).
The TRANSLATE_TABLE_FILEINFO command specifies a translation table to be used with file information such as comments, file names, andpassword usage for an encrypted file. The default is EBC#8859 if this command is not specified.
258
-TRANSLATE_TABLE_FILEINFO(<trantable>)
trantable - A name of a loadable translation table that is supplied with the product or customized by the installation.
Use this command when filenames are in an incompatible format with the target platform or when standard translation tables contain indecipherable characters from when the file was previously translated.
–UNZIPPED_DSN
Synonyms Include: –NOA, –HLQ, –UNZIPPED_DSNAME
One or more UNZIPPED_DSN commands may be used to modify high level qualifiers when extracting files. During filename transformation (from archive filename format to MVS data set name format), matching archive filename path qualifiers are replaced with an MVS high level qualifier specified in this command. A generalized renaming process can be made by using wildcard specifications.
The basic format of the command is:
–UNZIPPED_DSN([<Zipfile_path>],[<MVS_hlq>])
Note: Either field may be blank but not both.
Note: In previous versions of PKZIP for MVS, the ‘/’ character was used to separate the two parameters. Although this character may still work under some conditions, a comma ‘,’ is recommended as this is consistent with other commands and removes confusion about the use of the ‘/’ character in the Zip file name.
Sample renaming operations performed by this command:
High-Level Replacement
Given the archive filename:
MDB/TYPE/RATE
and a command of: –UNZIPPED_DSN(MDB.TY,XXX.)
(note delimiter in newname)
the result will be: XXX.PE.RATE
259
Given the archive filename:
MDB/TYPE/RATE
and a command of: –UNZIPPED_DSN(*,XXX)
(note use of wildcard for high level qualifier in oldname)
the result will be: XXX.TYPE.RATE
Given the archive filename:
MDB/TYPE/RATE
and a command of: –UNZIPPED_DSN(MDB.?YPE.,XXX)
(note delimiter in oldname)
the result will be: XXX.RATE
High-Level Prefixing
Given the archive filename:
MDB/TYPE/RATE
and a command of: –UNZIPPED_DSN(,NEW.)
(note delimiter in new name)
the result will be: NEW.MDB.TYPE.RATE
or a command of: –UNZIPPED_DSN(,NEW)
(note no delimiter in new name)
the result will be: NEWMDB.TYPE.RATE
High-Level Removal
Given the archive filename:
MDB/TYPE/RATE
and a command of: –UNZIPPED_DSN(M,)
the result will be: DB.TYPE.RATE
(with the “M” removed)
260
Complete Replacement
Given the archive filename:
MDB/TYPE/RATE
and a command of: –UNZIPPED_DSN(**,NEW.VER.DATA)
the result will be: NEW.VER.DATA
Special Directory Names
Given the archive filename:
Documents and Settings/michael_s/My Documents/readme.txt
and a command of: -FILE_EXTENSION=DROP
-HLQ(Documents and Settings/michael_s/My Documents/,MYHLQ.)
the result will be: MYHLQ.README
Retaining a File Extension
Given the archive
filename: Documents and Settings/michael_s/My Documents/readme.txt
and a command of: -FILE_EXTENSION=NAMEFILE
-HLQ(Documents and Settings/michael_s/My Documents/,MYHLQ.)
the result will be: MYHLQ.README.TXT
Parameter Usage
<Zipfile_path> defines the high-level qualifier characters of the input ZIP file name that are to be substituted by the <MVS_HLQ>. This value can be up to 80 characters long and may specify wild characters to assist in the matching. The wild characters that can be specified are:
“*” to match any number of characters (within one level).
“?” to match a single character (except a qualifier separation character).
<MVS_hlq> specifies the characters that are to be used to replace those specified in the first operand (if any) and prefixed to the remainder of the archive filename. A maximum of 54 characters may be specified and should match MVS dataset naming conventions.
‘*’
Processing Notes
If you are uncertain about the results that will be achieved by the use of UNZIPPED_DSN, it is recommended that trial runs be performed with the SIMULATE
261
command. This will cause SecureZIP for z/OS to issue standard extraction messages that contain the target DSN values without actually extracting the files. This avoids excessive processing time and errant dataset creation when undesired filename results are experienced.
The UNZIPPED_DSN command is not recommended when using NOHIERARCHY, OUTDD, or ZIPCUR commands, as these commands can also change the output dataset name used, in potentially conflicting ways.
The UNZIPPED_DSN command is processed after the FILE_EXTENSION command has been used. FILE_EXTENSION(DROP) causes the removal of the ‘extension’ in the ZIP file name, in which case the extension should not be used when specifying the Zipfile_path.
When attempting to extract files to PDS members, the command OUTFILE_DSNTYPE (PDS I PDSE) may be used in combination with this command. In addition, by specifying a PDS member mask in newname, a PDS target will be assumed. For example: UNZIPPED_DSNAME (**,MY.NEW.PDS(*)).
Message ZPAM183E will be issued when the target MVS name is determined to fail MVS naming conventions (such as when the resulting filename is too long for the target dataset type, or DSN qualifiers are not properly constructed with period separators).
ZPAM91I GENERATED MVS DSN LEVEL TOO LONG MAS.IR4006DZMTVT.
ZPAM183E UNZIPPED_DSN(…/ parm2) Name is invalid.
The input UNZIPPED_DSN commands are searched in the order specified until a match is found with the beginning of the ZIP archive file name. Although many commands may be specified to account for various filename matches, one and only one is used to resolve the MVS_hlq once a match is found.
–VSAM
Synonyms Include: –NOVSAM, –SELECT_VSAM
To access or not access VSAM files during wildcard selections the VSAM command is specified. This only occurs for wildcard cases.
–VSAM(Y|N)
Y - YES - Any VSAM files that are used in multiple data set selections are included when using a wildcard request.
N - NO - The VSAM file(s) within a file selection are ignored when the selection contains a wildcard. If no wildcard is used in the selection, the VSAM file is used regardless.
Note that all VSAM commands use the access methods services IDCAMS utility to help define a new (or update an existing) data component, for a VSAM cluster containing a ZIP archive. See the Access Methods Services manual for specific information on use of this parameter.
262
–VSAM_ACCOUNT
Synonyms Include: N/A
The VSAM_ACCOUNT parameter defines the accounting information to be provided to Access Methods Services during a DEFINE CLUSTER.
The IDCAMS equivalent for this command is ACCOUNT(accounting information).
-VSAM_ACCOUNT(<acctinfo>)
acctinfo - A 32-character field containing accounting information.
–VSAM_ATTEMPTS
Synonyms Include: –OUTATTEMPTS, –OUTDATAATT
The VSAM_ATTEMPTS parameter defines the number of password attempts that are permitted to Access Methods Services during a DEFINE CLUSTER.
The IDCAMS equivalent for this command is ATTEMPTS(number).
–VSAM_ATTEMPTS(<number>)
number - The number of attempts that will be allowed at the console in response to a prompting message.
–VSAM_AUTH_EP
Synonyms Include: –OUTAUTH, –OUTDATAAUTH
The VSAM_AUTH_EP parameter supplies the entry point of a user security verification routine to Access Methods Services during a DEFINE CLUSTER.
The IDCAMS equivalent for this command is AUTHORIZATION(entrypoint).
–VSAM_AUTH_EP(<entry point>)
entry point - The entry point name of your security verification routine.
See also VSAM_AUTH_STRING below.
263
–VSAM_AUTH_STRING
Synonyms Include: –OUTASTR, –OUTDATAASTR
The VSAM_AUTH_STRING parameter supplies a string of information to be passed to your security verification routine to Access Methods Services during a DEFINE CLUSTER.
The IDCAMS equivalent for this command is AUTHORIZATION(entrypoint string).
–VSAM_AUTH_STRING(<string>)
string - The string of information to be passed to your security verification routine.
See also VSAM_AUTH_EP above.
–VSAM_BUFFERSPACE
Synonyms Include: –ARCHBUFSPACE, –BUFSPACE, –BUFFERSPACE, –OUTBUFSPACE
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_BUFFERSPACE parameter defines the minimum space (in bytes) to be provided for buffers.
The IDCAMS equivalent for this command is BUFFERSPACE(size).
-VSAM_BUFFERSPACE(<buffer size>)
buffer size - Specifies the number of bytes to be provided for buffers.
Note: Access Method Services may modify the value to fit VSAM processing needs.
–VSAM_CATALOG
Synonyms Include: –ARCHCATALOG, –CATALOG, –OUTCATALOG
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_CATALOG parameter defines into which catalog the VSAM output file is to be defined. If the value is blank, then the system-defined catalog environment will be used. If the value is set to a catalog name, then the name will be used in the Define Cluster Cat(name) parameter. If the value is set to USE_ORIGINAL, then UNZIP processing will attempt to use a saved catalog attribute from the zip archive.
264
Warning: Care must be taken when using the USE_ORIGINAL option. An inappropriate catalog may be used which does not fit within the master/user catalog structure of the target system. This may occur because the high-level-qualifier does not match the alias entries in the master catalog; either because of a change of qualifier, for example, with UNZIPPED_DSN specifications, or because the original filename does not match the current operating environment. This can result in a file being allocated in the specified catalog, but inaccessible through normal system catalog structures. The unzip will fail and the dataset may not appear in standard catalog listings, even though the file was created.
The IDCAMS equivalent for this command is CATALOG(catname).
-VSAM_CATALOG(<catname>[/<password>])
or
-VSAM_CATALOG(USE_ORIGINAL)
catname - Specifies the name of the catalog in which the cluster is to be defined.
Password - Specifies the update or higher-level password.
USE_ORIGINAL - Specifies that UNZIP processing will attempt to use a saved catalog attribute from the archive.
–VSAM_CISIZE
Synonyms Include: –ARCHCISZ, –ARCHCISIZE, –OUTCISZ, –OUTCISIZE, –VSAMCISZ, VSAMCISIZE, –CISIZE
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_CISIZE parameter defines the size of the control intervals for the cluster.
The IDCAMS equivalent for this command is CONTROLINTERVALSIZE(size).
-VSAM_CISIZE(<size>)
size - Specifies (in bytes) the size of the control intervals for the cluster.
Note: Access Method Services may modify the value to fit VSAM processing needs.
–VSAM_CLUSTER_TYPE
Synonyms Include: –VSAM_TYPE, –VSAMTYPE, –OUTATTR, –VSAMESDS, –VSAMKSDS, –VSAMRRDS, –ESDS, –KSDS, –RRDS
- Some values may be restricted by the operating environment.
265
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_CLUSTER_TYPE command defines the file type of a VSAM cluster.
There are three IDCAMS equivalents for this command, which include INDEXED, NONINDEXED, and NUMBERED.
–VSAM_CLUSTER_TYPE(ESDS|NONINDEXED|INDEXED|NUMBERED|RRDS |KSDS)
NONINDEXED - Entry-Sequenced VSAM file.
ESDS - Entry-Sequenced VSAM file.
INDEXED - Key-Sequenced VSAM file.
KSDS - Key-Sequenced VSAM file.
NUMBERED - Relative Record VSAM file.
RRDS - Relative Record VSAM file.
The file attributes stored in the original file will be used to create a newly extracted file unless a specification is made from the above list.
–VSAM_CODE
Synonyms Include: –OUTCODE, –OUTDATACODE
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_CODE parameter supplies a code name for the cluster or component to Access Methods Services during a DEFINE CLUSTER.
The IDCAMS equivalent for this command is CODE(code).
–VSAM_CODE(<name>)
name - The code name for the cluster or component.
–VSAM_CONTROLPW
Synonyms Include: –OUTCONTROLPW, –OUTDATACTLPW
This command specifies the control password to be passed to Access Methods Services for the definition or update of a VSAM cluster or component.
The IDCAMS equivalent for this command is CONTROLPW(password).
266
–VSAM_CONTROLPW(<pwd>)
pwd - An 8-character field specifying the control password.
–VSAM_DATA_CISIZE
Synonyms Include: –ARCHDATACISZ, –ARCHDATACISIZE, –OUTDATACISZ, –OUTDATACISIZE
The VSAM_DATA_CISIZE command provides the ability to define the size of the control intervals for the data component of a VSAM cluster.
The IDCAMS equivalent for this command is CONTROLINTERVALSIZE(size).
-VSAM_DATA_CISIZE(<size>)
size - Specifies (in bytes) the size of the control intervals for the data component.
–VSAM_DATA_EXCEPTIONEXIT
Synonyms Include: –ARCHDATAEEXT, –OUTDATAEEXT
The VSAM_DATA_EXCEPTIONEXIT parameter defines the name of your module that is given control when a problem occurs during the IDCAMS processing of the data component of the cluster.
The IDCAMS equivalent for this command is EXCEPTIONEXIT(module name).
-VSAM_DATA_EXCEPTIONEXIT(<exceptname>)
exceptname - Specifies the name of your module (phase name) that will be given control when an exception occurs.
–VSAM_DATA_FILE
Synonyms Include: –ARCHDATAFILE, –OUTDATAFILE
Specifies the FILE parameter of the IDCAMS DEFINE CLUSTER command used to create the data component of a new or updated ZIP archive.
The IDCAMS equivalent for this command is FILE(ddname).
–VSAM_DATA_FILE(<ddname>)
ddname - Specifies a DD statement in the JCL.
267
–VSAM_DATA_NAME
Synonyms Include: –ARCHDATANAME, –OUTDATANAME
The VSAM_DATA_NAME command provides the ability to define a NAME parameter for the data component of a VSAM cluster.
The IDCAMS equivalent for this command is NAME(entryname).
–VSAM_DATA_NAME(<entryname>)
entryname - Specifies the name to be given to the data component of the cluster.
–VSAM_DATA_ORDERED
Synonyms Include: –ARCHDATAORD, –ARCHDATANORD, –OUTDATAORD, –OUTDATANORD
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_DATA_ORDERED command provides the ability to define an ORDERED parameter for the data component of a VSAM cluster.
The IDCAMS equivalent for this command is ORDERED|UNORDERED.
–VSAM_DATA_ORDERED(<ORDERED|UNORDERED>)
ORDERED - Specifies the volumes are to be used in the order in which they were listed in the VOLUMES parameter.
UNORDERED - Specifies the volumes are not to be used in the order in which they were listed in the VOLUMES parameter.
–VSAM_DATA_PRIMARY
Synonyms Include: –ARCHDATAPRI, –OUTDATAPRI
The VSAM_DATA_PRIMARY command provides the ability to define the primary value for space allocation in the DATA component of a VSAM cluster. Note that this command is used in conjunction with VSAM_DATA_SPACE_TYPE.
The IDCAMS equivalent for this command is CYLINDERS(primary), TRACKS(primary), or RECORDS(primary).
–VSAM_DATA_PRIMARY(<primary>)
primary - Specifies the number of units to be allocated (cylinders, tracks, records, kilobytes, or megabytes).
268
–VSAM_DATA_SECONDARY
Synonyms Include: –ARCHDATASEC, –OUTDATASEC
The VSAM_DATA_SECONDARY command provides the ability to define the secondary value for space allocation in the DATA component of a VSAM cluster. Note that this command is used in conjunction with VSAM_DATA_SPACE_TYPE.
The IDCAMS equivalent for this command is CYLINDERS(secondary), TRACKS(secondary), or RECORDS(secondary).
–VSAM_DATA_SECONDARY(<secondary>)
secondary - Specifies the number of units to be allocated (cylinders, tracks, records, kilobytes, or megabytes).
–VSAM_DATA_SPACE_TYPE
Synonyms Include: –ARCHDATASPACE, –OUTDATASPACE
- Some values may be restricted by the operating environment.
For a new or updated ZIP archive, the type of allocation units may be specified using the VSAM_DATA_SPACE_TYPE command.
Note that use of this command necessitates the use of VSAM_DATA_PRIMARY and VSAM_DATA_SECONDARY to define the specific extent values.
–VSAM_DATA_SPACE_TYPE(<CYL|KB|REC|MB|TRK>)
CYL - (also CYLS and CYLINDERS) allocation by cylinders.
KB - (also KILOBYTES) allocation by Kilobytes (for the ICF catalog environment only).
MB - (also MEGABYTES) allocation by Megabytes (for the ICF catalog environment only).
REC - (also RECORDS) allocation by records.
TRK - (also TRKS and TRACKS) allocation by tracks.
Also see VSAM_DATA_PRIMARY and VSAM_DATA_SECONDARY.
–VSAM_DATA_VOLUMES
Synonyms Include: –ARCHDATAVOL, –OUTDATAVOL, –VSAM_VOLUMES
The VSAM_DATA_VOLUMES command provides the ability to define a VOLUMES parameter for the data component of a VSAM cluster. Note that a maximum of 31 volumes are supported.
The IDCAMS equivalent for this command is VOLUMES(volser).
269
–VSAM_DATA_VOLUMES(<volser>[ <volser> …])
volser - Specifies a one-to-six-character volume serial number.
–VSAM_DATACLASS
Synonyms Include: N/A
This command pertains to DF/SMS allocation of new files when doing PKUNZIP processing. If you specify these classes, they will be passed to DF/SMS when data set allocation occurs.
–VSAM_DATACLASS(<SMS Data Class>)
See IBM’s DF/SMS manuals for further information about this parameter.
–VSAM_DUPLICATE_ERROR
Synonyms Include: –OUTDUPLICATES, –FAILONDUPKEYS, –IGNOREDUPKEYS
When extracting a file to a new VSAM keyed cluster, this command specifies the action to be taken if a duplicate key is detected.
–VSAM_DUPLICATE_ERROR(FAIL|IGNORE)
FAIL - Indicates that processing will be aborted if a duplicate key is encountered.
IGNORE - Indicates that processing will continue if a duplicate key is encountered.
–VSAM_ERASE
Synonyms Include: –ARCHERASE, –ARCHNOERASE
The VSAM_ERASE parameter defines that the data component that is being defined be erased when the cluster is deleted.
The IDCAMS equivalent for this command is ERASE|NOERASE.
–VSAM_ERASE(Y|N)
Y - YES - The IDCAMS DEFINE CLUSTER command equivalent is ERASE.
N - NO - The IDCAMS DEFINE CLUSTER command equivalent is NOERASE.
270
–VSAM_EXCEPTIONEXIT
Synonyms Include: –ARCHEEXT, –OUTEEXT
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_EXCEPTIONEXIT parameter defines the name of your module that is given control when a problem occurs during the IDCAMS processing of the cluster component.
The IDCAMS equivalent for this command is EXCEPTIONEXIT(module name).
-VSAM_EXCEPTIONEXIT(<entrypoint>)
exceptname - Specifies the name of your module (phase name) that will be given control when an exception occurs.
–VSAM_FILE
Synonyms Include: –ARCHFILE
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_FILE parameter defines the name of the job control DD statement that identifies the volumes that are to be used for space allocation.
The IDCAMS equivalent for this command is FILE(ddname).
-VSAM_FILE(<ddname>)
ddname - Specifies a DD statement in the JCL.
–VSAM_FOR
Synonyms Include: –ARCHFOR
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_FOR parameter defines the retention date for the cluster.
The IDCAMS equivalent for this command is FOR(days).
-VSAM_FOR(<days>)
Note that specification of either the VSAM_TO or VSAM_FOR commands could prevent an old ZIP archive from being deleted during an update if the old archive had an active retention period.
271
–VSAM_FREESPACE_CA
Synonyms Include: –ARCHFREECA, –OUTFREECA
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_FREESPACE_CA command provides the ability to define the CA-percent parameter for a key-sequenced VSAM cluster.
-VSAM_FREESPACE_CA(<ca-percent>)
ca-percent - Specifies the percentage of control area that is to be left empty.
–VSAM_FREESPACE_CI
Synonyms Include: –ARCHFREECI
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_FREESPACE_CI command provides the ability to define the CI-percent parameter for a VSAM key-sequenced cluster.
-VSAM_FREESPACE_CI(<ci-percent>)
ci-percent - Specifies the percentage of control interval that is to be left empty.
–VSAM_IMBED
Synonyms Include: –OUTIMBED, –OUTNOIMBED
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_IMBED command provides the ability to define an IMBED parameter for a VSAM cluster.
The IDCAMS equivalent for this command is IMBED|NOIMBED.
–VSAM_IMBED(Y|N)
Y - YES - Specifies that the sequence set is to be placed with the data component of a new cluster.
N - NO - Specifies that the sequence set is not to be placed with the data component of a new cluster.
272
–VSAM_INDEX_ATTEMPTS
Synonyms Include: –OUTINDXATT
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_ATTEMPTS parameter defines the number of password attempts that are permitted to Access Methods Services during a DEFINE CLUSTER.
The IDCAMS equivalent for this command is ATTEMPTS(number).
–VSAM_INDEX_ATTEMPTS(<number>)
number - The number of attempts that will be allowed at the console in response to a prompting message.
–VSAM_INDEX_AUTH_EP
Synonyms Include: –OUTINDXAUTH
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_AUTH_EP parameter supplies the entry point of a user security verification routine to Access Methods Services during a DEFINE CLUSTER.
The IDCAMS equivalent for this command is AUTHORIZATION(entrypoint).
–VSAM_INDEX_AUTH_EP(<entry point>)
entry point - The entry point name of your security verification routine.
–VSAM_INDEX_AUTH_STRING
Synonyms Include: –OUTINDXASTR
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_AUTH_STRING parameter supplies a string of information to be passed to your security verification routine to Access Methods Services during a DEFINE CLUSTER.
The IDCAMS equivalent for this command is AUTHORIZATION(entrypoint string).
–VSAM_INDEX_AUTH_STRING(<string>)
string - The string of information to be passed to your security verification routine.
See also VSAM_INDEX_AUTH_EP above.
273
–VSAM_INDEX_CISIZE
Synonyms Include: –OUTINDXCISZ, –OUTINDXCISIZE
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_CISIZE command provides the ability to define a CONTROLINTERVALSIZE for the index component of a VSAM cluster.
The IDCAMS equivalent for this command is CONTROLINTERVALSIZE(size).
–VSAM_INDEX_CISIZE(<size>)
size - Specifies the size of the control intervals for the index component.
–VSAM_INDEX_CODE
Synonyms Include: N/A
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_CODE parameter supplies a code name for the cluster or component to Access Methods Services during a DEFINE CLUSTER.
The IDCAMS equivalent for this command is CODE(code).
–VSAM_INDEX_CODE(<name>)
name - Specifies the code name for the index component.
–VSAM_INDEX_CONTROLPW
Synonyms Include: –OUTINDXCTLPW
- Be aware that if this command is used incorrectly, you could incur problems.
This command specifies the control password to be passed to Access Methods Services for the definition or update of the index component of a VSAM cluster.
The IDCAMS equivalent for this command is CONTROLPW(password).
–VSAM_INDEX_CONTROLPW(<pwd>)
pwd - Specifies a one-to-eight-character control password.
274
–VSAM_INDEX_EXCEPTIONEXIT
Synonyms Include: –OUTINDXEEXT
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_EXCEPTIONEXIT command provides the ability to define an EXCEPTIONEXIT parameter for the index component of a VSAM cluster.
The IDCAMS equivalent for this command is EXCEPTIONEXIT(module name).
-VSAM_INDEX_EXCEPTIONEXIT(<exceptname>)
exceptname - Specifies the name of your module (phase name) that will be given control when an exception occurs.
–VSAM_INDEX_FILE
Synonyms Include: –OUTINDXFILE
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_FILE command provides the ability to define an INDEX parameter for the index component of a VSAM cluster.
The IDCAMS equivalent for this command is FILE(ddname).
–VSAM_INDEX_FILE(<ddname>)
ddname - Specifies a DD statement in the JCL.
–VSAM_INDEX_MASTERPW
Synonyms Include: –OUTINDXMRPW
- Be aware that if this command is used incorrectly, you could incur problems.
This command specifies the master password to be passed to Access Methods Services for the definition or update of the index component of a VSAM cluster.
The IDCAMS equivalent for this command is MASTERPW(password).
–VSAM_INDEX_MASTERPW(<pwd>)
pwd - An 8-character field specifying the master password.
275
–VSAM_INDEX_NAME
Synonyms Include: –OUTINDXNAME
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_NAME command provides the ability to define a NAME parameter for the index component of a VSAM cluster.
The IDCAMS equivalent for this command is NAME(entryname).
–VSAM_INDEX_NAME(<entryname>)
entryname - Specifies the name to be given to the index component of the cluster.
–VSAM_INDEX_ORDERED
Synonyms Include: –OUTINDXORD, –OUTINDXNORD
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_ORDERED command provides the ability to define an ORDERED parameter for the index component of a VSAM cluster.
The IDCAMS equivalent for this command is ORDERED|UNORDERED.
–VSAM_INDEX_ORDERED(<ORDERED|UNORDERED>)
ORDERED - Specifies the volumes are to be used in the order in which they were listed in the VOLUMES parameter.
UNORDERED - Specifies the volumes are not to be used in the order in which they were listed in the VOLUMES parameter.
–VSAM_INDEX_PRIMARY
Synonyms Include: –OUTINDXPRI
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_PRIMARY command provides the ability to define the primary value for space allocation in the INDEX component of a VSAM cluster. Note that this command is used in conjunction with VSAM_INDEX_SPACE_TYPE.
The IDCAMS equivalent for this command is CYLINDERS(primary), TRACKS(primary), or RECORDS(primary).
276
–VSAM_INDEX_PRIMARY(<primary>)
primary - Specifies the number of units to be allocated (cylinders, tracks, records, kilobytes, or megabytes).
Also see VSAM_INDEX_SECONDARY.
–VSAM_INDEX_READPW
Synonyms Include: –OUTINDXRDPW
- Be aware that if this command is used incorrectly, you could incur problems.
This command specifies the read password to be passed to Access Methods Services for the definition or update of the index component of a VSAM cluster.
The IDCAMS equivalent for this command is READPW(password).
–VSAM_INDEX_READPW(<pwd>)
pwd - An 8-character field specifying the read password.
–VSAM_INDEX_SECONDARY
Synonyms Include: –OUTINDXSEC
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_SECONDARY command provides the ability to define the secondary value for space allocation in the INDEX component of a VSAM cluster. Note that this command is used in conjunction with VSAM_INDEX_SPACE_TYPE.
The IDCAMS equivalent for this command is CYLINDERS(secondary), TRACKS(secondary), or RECORDS(secondary).
–VSAM_INDEX_SECONDARY(<secondary>)
secondary - Specifies the number of units to be allocated (cylinders, tracks, records, kilobytes, or megabytes).
Also see VSAM_INDEX_PRIMARY.
277
–VSAM_INDEX_SPACE_TYPE
Synonyms Include: –OUTINDXSPACE
- Some values may be restricted by the operating environment.
- Be aware that if this command is used incorrectly, you could incur problems.
For a new or updated ZIP archive, the type of index units may be specified using the VSAM_INDEX_SPACE_TYPE command.
Note that use of this command necessitates the use of VSAM_INDEX_PRIMARY and VSAM_INDEX_SECONDARY to define the specific extent values.
The IDCAMS equivalent for this command is CYLINDERS, TRACKS, or RECORDS.
–VSAM_INDEX_SPACE_TYPE(<CYL|KB|REC|MB|TRK>)
CYL - (also CYLS and CYLINDERS) allocation by cylinders.
KB - (also KILOBYTES) allocation by Kilobytes (for the ICF catalog environment only).
MB - (also MEGABYTES) allocation by Megabytes (for the ICF catalog environment only).
REC - (also RECORDS) allocation by records.
TRK - (also TRKS and TRACKS) allocation by tracks.
Note that both the primary and secondary extents are allocated at 10 allocation units unless changed by the VSAM_SPACE_PRIMARY or the VSAM_SPACE_SECONDARY commands.
Also see VSAM_INDEX_PRIMARY and VSAM_INDEX_SECONDARY.
–VSAM_INDEX_UPDATEPW
Synonyms Include: –OUTINDXUPDPW
- Be aware that if this command is used incorrectly, you could incur problems.
This command specifies the update password to be passed to Access Methods Services for the definition or update of the index component of a VSAM cluster.
The IDCAMS equivalent for this command is UPDATEPW(password).
–VSAM_INDEX_UPDATEPW(<pwd>)
pwd - An 8-character field specifying the update password.
278
–VSAM_INDEX_VOLUMES
Synonyms Include: –OUTINDXVOL
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_INDEX_VOLUMES command provides the ability to define a VOLUMES parameter for the index component of a VSAM cluster. Note that a maximum of 31 volumes are supported.
The IDCAMS equivalent for this command is VOLUMES(volser).
–VSAM_INDEX_VOLUMES(<volser>[ <volser> …])
volser - Specifies volume serial numbers sequenced by a blank.
–VSAM_KEYS
Synonyms Include: –OUTKEYS
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_KEYS command provides the ability to specify information about key fields for a VSAM key-sequenced file (ignored for entry-sequenced or relative-record files).
The IDCAMS equivalent for this command is KEYS(length offset).
–VSAM_KEYS(length offset)
length - Defines the length of a key for a key-sequenced file (255-byte maximum).
Offset - Defines the offset of the key from the front of the data record.
–VSAM_MASTERPW
Synonyms Include: –OUTMASTERPW, –OUTDATAMRPW
- Be aware that if this command is used incorrectly, you could incur problems.
This command specifies the master password to be passed to Access Methods Services for the definition or update of a VSAM cluster or component.
The IDCAMS equivalent for this command is MASTERPW(password).
279
–VSAM_MASTERPW(<pwd>)
pwd - An 8-character field specifying the master password.
–VSAM_MGMTCLASS
Synonyms Include: N/A
- Be aware that if this command is used incorrectly, you could incur problems.
This command pertains to DF/SMS allocation of new files when doing PKUNZIP processing. If you specify these classes, they will be passed to DF/SMS when data set allocation occurs.
–VSAM_MGMTCLASS(<SMS Management Class>)
See IBM’s DF/SMS manuals for further information about this parameter.
–VSAM_MODEL
Synonyms Include: –ARCHMODEL, –ARCHIVE_MODEL, –OUTMODEL
- Be aware that if this command is used incorrectly, you could incur problems.
This command specifies that a catalog entry of a previously defined cluster is to be used as the model for a new archive.
The IDCAMS equivalent for this command is MODEL(entryname).
–VSAM_MODEL(<entryname>)
entryname - A 44-character entry used to specify the model.
–VSAM_ORDERED
Synonyms Include: N/A
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_ORDERED command provides the ability to define an ORDERED parameter for a VSAM cluster.
The IDCAMS equivalent for this command is ORDERED|UNORDERED.
280
–VSAM_ORDERED(<ORDERED|UNORDERED>)
ORDERED - Specifies the volumes are to be used in the order in which they were listed in the VOLUMES parameter.
UNORDERED - Specifies the volumes are not to be used in the order in which they were listed in the VOLUMES parameter.
–VSAM_OWNER
Synonyms Include: –ARCHDATAOWNER, –ARCHOWNER, –OUTDATAOWNER, OUTINDXOWNER, –OUTOWNER
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_OWNER command provides the ability to define an OWNER parameter for a VSAM cluster.
The IDCAMS equivalent for this command is OWNER(owner ID).
-VSAM_OWNER(<owner>)
owner - Specifies a one-to-eight-character owner ID of the cluster.
–VSAM_READPW
Synonyms Include: –OUTREADPW, –OUTDATARDPW
- Be aware that if this command is used incorrectly, you could incur problems.
This command specifies the read password to be passed to Access Methods Services for the definition or update of a VSAM cluster or component.
The IDCAMS equivalent for this command is READPW(password).
–VSAM_READPW(<pwd>)
pwd - An 8-character field specifying the read password.
–VSAM_RECORDSIZE
Synonyms Include: –ARCHRECORDSIZE
- Be aware that if this command is used incorrectly, you could incur problems.
281
The VSAM_RECORDSIZE parameter defines the average and maximum lengths of the data records of a variable length file.
The IDCAMS equivalent for this command is RECORDSIZE(average maximum).
-VSAM_RECORDSIZE(<average> <maximum>)
<average> - The average length in bytes of each record.
<maximum> - The maximum length of any record.
The default for this command is (4000 4000).
It is suggested <average> = <maximum> for PKZIPz processing since full-length records are written in the process. Also, a larger value for both parameters will improve PKZIPz performance.
–VSAM_RECOVERY_OPT
Synonyms Include: –OUTRECOVERY, –OUTSPEED
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_RECOVERY_OPT command provides the ability to define a SPEED or RECOVERY parameter for a VSAM cluster.
The IDCAMS equivalent for this command is RECOVERY|SPEED.
–VSAM_RECOVERY_OPT(recovery|speed)
recovery - Specifies that the data component control areas are written with records that indicate an end-of-file indicator.
speed - Specifies that the data component control areas are not preformatted.
–VSAM_REPLICATE
Synonyms Include: –OUTREPLICATE, –OUTNOREPLICATE
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_REPLICATE command provides the ability to define a REPLICATE parameter for a VSAM cluster.
The IDCAMS equivalent for this command is REPLICATE|NOREPLICATE.
282
–VSAM_REPLICATE(Y|N)
–VSAM_REUSE
Synonyms Include: –ARCHREUSE, –ARCHNOREUSE, –ARCHDATARUS, ARCHDATANRUS, –OUTREUSE, –OUTNOREUSE, –OUTDATARUS, OUTDATANRUS, –OUTINDXRUS, OUTINDXNRUS
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_REUSE parameter defines whether the newly-defined file can be opened repeatedly as a new file.
The IDCAMS equivalent for this command is REUSE|NOREUSE.
-VSAM_REUSE(Y|N)
Y - YES - Specifies that REUSE be passed to the DEFINE CLUSTER command.
N - NO - Specifies that NOREUSE be passed to the DEFINE CLUSTER command.
–VSAM_SHAREOPTIONS
Synonyms Include: –ARCHSHR, –ARCHDATASHR, –OUTSHR, –OUTDATASHR, OUTINDXSHR, –VSAM_SHROPTS, –VSAM_SHROPT
- Be aware that if this command is used incorrectly, you could incur problems.
–VSAM_SHAREOPTIONS(value1|value2)
The VSAM_SHAREOPTIONS parameter defines how a file can be shared within or between systems.
The IDCAMS equivalent for this command is SHAREOPTIONS(value1 value2).
Crossregion - Specifies the level of sharing among regions.
Crosssystem - Specifies the level of sharing among systems.
–VSAM_SPACE_PRIMARY
Synonyms Include: N/A
- Some values may not be restricted by the operating environment.
283
- Be aware that if this command is used incorrectly, you could incur problems.
For a new or updated ZIP archive, the number of allocation units in the primary extent is specified using the VSAM_SPACE_PRIMARY command.
The default is not used if VSAM_DATACLASS is specified.
The IDCAMS equivalent for this command is CYLINDERS(primary), TRACKS(primary), RECORDS(primary), KILOBYTES(primary), or MEGABYTES(primary).
–VSAM_SPACE_PRIMARY(<primary>)
primary - An 8-character field specifying the number of allocation units for the primary extent of the new or updated ZIP archive.
00000010 - Ten (cylinders) is the default.
–VSAM_SPACE_SECONDARY
Synonyms Include: N/A
- Be aware that if this command is used incorrectly, you could incur problems.
For a new or updated ZIP archive, the number of allocation units in the secondary extent is specified using the VSAM_SPACE_SECONDARY command. If specified, the data unit number must not be 0.
The default is not used if VSAM_DATACLASS is specified.
The IDCAMS equivalent for this command is CYLINDERS(secondary), TRACKS(secondary), RECORDS(secondary), KILOBYTES(secondary), or MEGABYTES(secondary).
–VSAM_SPACE_SECONDARY(<secondary>)
secondary - An 8-character field specifying the number of allocation units for the secondary extent of the new or updated ZIP archive.
00000010 - Ten (cylinders) is the default.
–VSAM_SPACE_TYPE
Synonyms Include: N/A
- Some values may not be restricted by the operating environment.
- Be aware that if this command is used incorrectly, you could incur problems.
284
For a new or updated ZIP archive, the type of allocation units may be specified using the VSAM_SPACE_TYPE command. Note the default is not used when VSAM_DATACLASS is specified.
The IDCAMS equivalent for this command is CYLINDERS, TRACKS, or RECORDS.
–VSAM_SPACE_TYPE(<CYL|KB|REC|MB|TRK>)
CYL - (also CYLS and CYLINDERS) allocation by cylinders.
KB - (also KILOBYTES) allocation by Kilobytes (for the ICF catalog environment only).
MB - (also MEGABYTES) allocation by Megabytes (for the ICF catalog environment only).
REC - (also RECORDS) allocation by records.
TRK - (also TRKS and TRACKS) allocation by tracks.
This command specification can be overridden at the data level by the VSAM_DATA_SPACE_TYPE command. At the data level, the corresponding cluster information is not recognized.
–VSAM_SPANNED
Synonyms Include: –ARCHSPANNED, –ARCHNONSPANNED
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_SPANNED parameter defines whether the maximum length of a data record can be greater than the control interval size.
The IDCAMS equivalent for this command is SPANNED|NONSPANNED.
-VSAM_SPANNED(Y|N)
Y - YES - The IDCAMS DEFINE CLUSTER command equivalent is SPANNED.
N - NO - The IDCAMS DEFINE CLUSTER command equivalent is NONSPANNED.
–VSAM_STORCLASS
Synonyms Include: N/A
- Be aware that if this command is used incorrectly, you could incur problems.
This command pertains to DF/SMS allocation of new files when doing PKUNZIP processing. If you specify these classes, they will be passed to DF/SMS when data set allocation occurs.
285
–VSAM_STORCLASS(<SMS Storage Class>)
See IBM’s DF/SMS manuals for further information about this parameter.
–VSAM_TO
Synonyms Include: –ARCHFOR, –ARCHTO, –OUTFOR, –OUTTO
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_TO parameter defines the retention date for the cluster.
The IDCAMS equivalent for this command is TO(date).
-VSAM_TO(<date>)
date - Specifies the date until which the cluster is to be retained.
Note: The specification of either the –VSAM_TO or –VSAM_FOR commands could prevent an old ZIP archive from being deleted during an update if the old archive had an active retention period.
–VSAM_UPDATEPW
Synonyms Include: –OUTUPDATEPW, –OUTDATAUPDPW
- Be aware that if this command is used incorrectly, you could incur problems.
This command specifies the update password to be passed to Access Methods Services for the definition or update of a VSAM cluster or component.
The IDCAMS equivalent for this command is UPDATEPW(password).
–VSAM_UPDATEPW(<pwd>)
pwd - An 8-character field specifying the update password.
286
–VSAM_WRITECHECK
Synonyms Include: –ARCHWRITECHK, –ARCHNOWRITECHK, –ARCHDATAWCK, ARCHDATANWCK, –OUTDATAWCK, –OUTDATANWCK, –OUTWRITECHK, –OUTNOWRITECHK
- Be aware that if this command is used incorrectly, you could incur problems.
The VSAM_WRITECHECK parameter defines whether to verify the transfer of records written to the cluster.
The IDCAMS equivalent for this command is WRITECHECK|NOWRITECHECK.
–VSAM_WRITECHECK(WRITECHECK|NOWRITECHECK)
WRITECHECK - The IDCAMS DEFINE CLUSTER command equivalent is WRITECHECK.
NOWRITECHECK - The IDCAMS DEFINE CLUSTER command equivalent is NOWRITECHECK.
–ZIP_UNMOVABLE_CHKPT
Synonyms Include: none
- Be aware that if this command is used incorrectly, you could incur problems.
-ZIP_UNMOVABLE_CHKPT(Y|N)
Y - YES – Allow ZIP processing of sequential data sets have both the CHECKPOINT and UNMOVABLE attributes set in the VTOC.
N - NO – Treat CHECKPOINT data sets the same as all other data sets and bypass ZIP processing when the UNMOVABLE flag is set. (This is the default)
In general, unmovable data sets are not supported because these types of files normally contain location-dependent data that is beyond the scope of ZIP processing. However, IBM has introduced a change in Checkpoint/Restart beginning with DF/SMS 1.4 to set the UNMOVABLE attribute for every SMS-managed sequential data set that is open at the time a checkpoint is taken. Limited ZIP support has been added for data sets having both the CHECKPOINT and UNMOVABLE flags set in the format1 DSCB.
Ref: IBMLINK Item II11474 and Info APAR II11696 for more information.
Usage Notes
When a file is detected that matches the criteria for ZIP_UNMOVABLE_CHKPT, message ZPFM013I will be issued to SYSPRINT.
287
When an UNMOVABLE CHECKPOINT data set is processed during ZIP processing, these attributes are not retained within the ZIP Archive. (It is treated as a normal sequential data set).
If the data set is pre-allocated on the system without the UNMOVABLE attribute in the VTOC, or if it does not exist on the system, UNZIP processing will restore the data set.
UNZIP will reject an attempt to overwrite an existing data set which has the UNMOVABLE attribute currently set in the VTOC in order to maintain its integrity. Message ZPFM014W or ZPEX018W will be issued for each file found with this condition.
This command replaces functional fix TT1825 using PROC_OPT5 in earlier releases of the product. Installations previously using PROC_OPT5 are encouraged to use ZIP_UNMOVABLE_CHKPT. PROC_OPT5 is still active in this release, with differences in message notifications as noted above.
–ZIPPED_DSN
Synonyms Include: –NIA
- Be aware that if this command is used incorrectly, you could incur problems.
The ZIPPED_DSN command specifies one or more MVS file names and how they are to be renamed for the associated ZIP file. More than one file may be referenced in one command by the use of wildcard characters. The default depends on the MVS file type and other situations as outlined below.
–ZIPPED_DSN(<MVS name>,<Archive name>)
MVS name - One entry representing one or more MVS file names. The maximum character length is 54 characters. Spaces are not valid. Wildcard characters (“*”) may be used here for two purposes:
To identify more than one file. <MVS name> = MYFILE.NEW* represents MYFILE.NEW1, MYFILE.NEW2, MYFILE.NEW3, and so on.
To identify the part of the <MVS name> to be used in the <Archive name>. A matching wildcard character in the <Archive name> indicates the corresponding part of the <MVS name> is duplicated in the <Archive name>.
See the table below for examples.
Archive name - The format for the associated ZIP file name(s). The maximum character length is 80 characters. Embedded spaces are supported. The entry contains the ZIP file component name and may contain wildcard characters(“*”) and ignore characters (“+”). Each wildcard character matches a wildcard character in the <MVS name> and copies that character from the <MVS name> into the ZIP archive name at the “*” location. Each ignore character matches with a wildcard character in the <MVS name> and does not copy that character from the <MVS name> into the Zip archive name at the “+” location. (See below).
See the table below for ZIPPED_DSN examples:
288
<MVS file> <MVS name>,<Archive name> ZIP File name results
MVS.SEQ.INFO MVS.SEQ.INFO,ZIP/INF ZIP/INF
MVS.SEQ.INFO MVS.SEQ.INFO,ZIP.EXT ZIP.EXT
MVS.PDS(MEM1) MVS.PDS(*),ZIP/LIB/* ZIP/LIB/MEM1
MVS.PDS(MEM2) Allow to default ZIP/LIB/MEM2
MVS.PDS(MEMN) *.*(MEMN),*/*.DAT MVS/PDS.DAT
MVS.PDS(MEMN) *.*(*),*/*/*.DAT MVS/PDS/MEMN.DAT
MVS.PDS(MEMN) *.PDS(*),*/*/INFO MVS/MEMN/INFO
MVS.PDS(MEMN) *(*),+*.INF MEMN.INF
MVS.SEQ.INFO *.*.INFO,*.* MVS.SEQ
MVS.SEQ.INFO *.*.DATA,+*.INF SEQ.INF
More than one ZIPPED_DSN command can be used in one execution to match various input/output combinations. File names are converted based on the order of occurrence of ZIPPED_DSN commands. In the following example, the file MYFILE.INPUT.DAT would be processed by the second ZIPPED_DSN command.
MYFILE.INPUT.DAT –ZIPPED_DSN(*.IN.*,*/*) –ZIPPED_DSN(*.INPUT,*/*.DAT) (here the file is processed) –ZIPPED_DSN(*.DATA,*/DAT) ZPAM253I ADDED File MYFILE.INPUT.DAT ZPAM254I as MYFILE/INPUT/DAT.TXT ZPAM255I (DEFLATED 62%/61%)
This would create the ZIP file: MYFILE/INPUT.DAT.
Notes for –ZIPPED_DSN File names are converted based on the order of occurrence of ZIPPED_DSN commands. For example, the file MYFILE.INPUT.DAT would be processed by the second ZIPPED_DSN command in the following example.
–ZIPPED_DSN(*.IN.*,*/*)
–ZIPPED_DSN(*.INPUT,*/*.DAT) (here the file is processed)
–ZIPPED_DSN(*.DATA,*/DAT)
This would create the ZIP file: MYFILE/INPUT.DAT.
Care must be taken when coding this command to achieve a desired result. Examples of errant coding techniques follows:
289
Example:
Given the PDS member:
MVS.PDS(MEMBER)
and a command of: –ZIPPED_DSN(*,*.TXT)
the ZIP archive will be: MVS.PDS(MEMBER).TXT
(an invalid filename)
or
Given the PDS member:
MVS.PDS(MEMBER)
and a command of: –ZIPPED_DSN(MV*,PD*.TXT)
the ZIP archive will be: PDS.PDS(MEMBER).TXT
(an invalid filename)
When coding this command for new filename translation, the SIMULATE command can be used in test runs to ensure that the desired results are being achieved without the processing time associated with compression and archiving.
The allowable number of ZIPPED_DSN commands is determined by each command’s storage requirements of approximately 256 bytes.
The allowable number of wild characters (“*”) is determined by the <MVS name> format. Extra wild characters adjacent to other wild characters are not supported. The maximum number of wild characters in the <MVS name> is 28.
There must be a match of wild characters in the <Archive name> to the <MVS name> or unpredictable results may occur. Any extra wild characters in the <MVS name> are ignored. For example, a null filename may result from ZIPPED_DSN(*,+), which instructs all MVS DSN characters to be deleted.
Defaults for –ZIPPED_DSN If the ZIPPED_DSN command is not specified, the default ZIP file name depends on the MVS file type.
NonVSAM files Periods for all data set types and the left-parenthesis associated with PDS and PDSE member formats are converted to the active ZIPPED_DSN_SEPARATOR character. The right-parenthesis for member name designations are ignored. For example:
–ARCHIVE(MY.TEMP.ZIP) –ACTION(UPDATE) DEV.IVP.SEQ DEV.PROJ.SRC(ASCIIUS) ZPAM030I OUTPUT Archive opened: MY.TEMP.ZIP ZPAM253I ADDED File DEV.IVP.SEQ ZPAM254I as DEV/IVP/SEQ ZPAM255I (DEFLATED 78%/78%) ZPAM253I ADDED File DEV.PROJ.SRC(ASCIIUS) ZPAM254I as DEV/PROJ/SRC/ASCIIUS ZPAM255I (DEFLATED 62%/61%)
290
Note that the command PATH(N) may change the expected path name, and ZIPPED_DSN_SEPARATOR can create a file with the command’s specified separators. If the ZIPPED_DSN command is not specified, verify that the path and separators are specified correctly.
VSAM Clusters for –ZIPPED_DSN The ZIPPED_DSN specifications are also applied to the index and the data levels of file names, which are stored as attributes within the archive. Separate ZIPPED_DSN commands cannot be applied to the component names.
The created DATA and INDEX names are appended with “.DATA” and “.INDX” respectively. The MVS separator “.” is used rather than the active value of ZIPPED_DSN_SEPARATOR.
-ACTION(ADD) -ARCHIVE_DSN(MAS.TEMP.ZIP) -ARCHIVE_DSORG(PS) -ACTION(UPDATE) MAS.TEST.KSDS -ZIPPED_DSN(MAS.*.KSDS,MAS/NEWLVL/KSDS) ZPAM030I OUTPUT Archive opened: MAS.TEMP.ZIP ZPAM253I ADDED File MAS.TEST.KSDS ZPAM254I as MAS/NEWLVL/KSDS ZPAM255I (DEFLATED 91%/91%) Resulting values: -ACTION(VIEWDETAIL) ZPAM001I Filename: MAS/NEWLVL/KSDS ZPAM332I VSAM Data Name: MAS.NEWLVL.KSDS.DATA ZPAM333I VSAM Index Name: MAS.NEWLVL.KSDS.INDEX
–ZIPPED_DSN_SEPARATOR
Synonyms Include: –NIASEP
To specify the separator to be used in the created ZIP archive name, ZIPPED_DSN_SEPARATOR command is used. The default is “/” or Hex ‘2F’ to conform to ZIP Specifications, which provides for cross-platform compatibility. This creates a file name where each MVS qualifier is converted to a directory name. For example, period separators are changed to the specified separator character.
–ZIPPED_DSN_SEPARATOR(<sepchar>)
sepchar - The character to be used as a separator between components in the ZIP file name. It may be coded in one of two formats:
EBCDIC Display Character - Where the character is a single EBCDIC character. This will be translated with the TRANSLATE_TABLE_FILEINFO table to ASCII before used in the ZIP file. A “/” is the default character.
X’Hex’ - Where the actual ASCII character is specified in hex and is not translated before placed in the ZIP file. A hex character of “2F” is the default character.
291
Note: Use of a separator character other than the default should be done with consideration of the targeted PKUNZIP system. Unexpected results may occur during an extract if the filename does not adhere to the target system’s file naming standards.
Example:
Given the PDS member:
XXX.YYY(ZZZ)
and a command of: (not specified: using the default value of “/”)
the ZIP archive will be: XXX/YYY/ZZZ
Example:
Given the PDS member:
XXX.YYY(ZZZ)
and a command of: –ZIPPED_DSN_SEPARATOR($)
the ZIP archive will be: XXX$YYY$ZZZ
292
11 ZIP Archives
A ZIP archive is the storage facility for files that are compressed, or simply stored using the PKZIPz product. It can hold up to 65,535 files, which may be compressed up to 99% of their original size. File attributes are retained to allow extraction of the same file characteristics without the need of control card specifications. Data integrity is validated by a cyclic redundancy check (CRC) to ensure integrity from compression through extraction.
An archive can exist in three possible states during processing. These are “old archive,” “temporary data set,” and “new archive.” An explanation of the functions of each of these is described in the sections below.
Many older ZIP products were modeled after the disk-operating system, (DOS)-based PKZIP® products, which had an archive limit of 16,383 files. The current ZIP archive specifications allow up to 65,535 files based on a two-byte binary counter in the directory. An archive that is created by PKZIP or SecureZIP for z/OS with greater than 16,383 files may not be able to be processed by older releases of PKZIP for z/OS or ZIP products written by other vendors. The actual number of files that can be processed by PKZIPz is limited by local system resources such as allowable region size.
A ZIP archive is transferable between platforms. For example, files compressed by PKZIPz can be extracted by PKZIP on a different platform and maintain identical data.
MVS archives can be held in a variety of formats: sequential data set on tape or disk, PDS or PDSE members, or a VSAM cluster (ESDS). An archive file is designated to PKZIPz by a control card of either ARCHIVE_DSN(dsname) or ARCHIVE_INFILE(ddname).
Sequential data set archives may be held in Undefined (U), Variable (V, VB) or Fixed (F, FB, FBS) formats. PDS and PDSE member archives may be held in Undefined (U), or Fixed (F, FB) formats.
The standard format for a ZIP archive is shown in the table below:
293
Standard Zip Archive Format
File #1 [Local Directory Entry (X’504B0304’)] [optional extended attributes][file data]
File #2 [Local Directory Entry (X’504B0304’)] [optional extended attributes][file data]
File #n [Local Directory Entry (X’504B0304’)] [optional extended attributes][file data]
File #1 [Central Directory Entry (X’504B0102’)] [optional extended attributes]
File #2 [Central Directory Entry (X’504B0102’)] [optional extended attributes]
File #n [Central Directory Entry (X’504B0102’)] [optional extended attributes]
[End-Central Directory Entry (X’504B0506’)] [optional Archive Comment]
The local and central directory entries contain information such as the file name, uncompressed size and compressed size, along with control values. The extended information controlled by the SAVE_FILE_ATTRIBUTES command reflects data set allocation information from the file as stored by PKZIPz.
“Old” ZIP Archive
An old ZIP archive refers to an archive containing ZIPPED files that is in existence and may also be referred to as “ARCHIN”. It may have been created by PKZIPz in an earlier process, or have been transferred from a different platform. This archive is specified using the ARCHIVE or ARCHIVE_INFILE commands. The old archive can be thought of as the “before” version of an archive that is being updated.
“Temporary” Dataset
A temporary data set refers to a work in progress. This data set has several possible uses in PKZIPz processing, including:
X'Hex' - Here the actual ASCII character is specified in hex and is not translated before placed in the ZIP file. A hex character of “2F” is the default character.
When a new non-partitioned archive data set is created by an update request, PKZIPz will use a temporary name for the output archive until the processing request is complete. Note that the system reports the cataloging of the temporary dataset name in the job log, not the final name used in the rename. This is normal behavior for dynamically allocated files in System/390 operating systems.
As an interim storage area for compressed data before it is written to the output archive.
In addition to the archive being allocated, temporary files may be allocated as staging areas for compressed data. The –TEMP family of commands governs the allocation controls for these temporary files.
As temporary storage while processing tape input archives.
294
The –STAGE_TAPE_TO_DISK command may be used to copy a tape archive to a disk based temporary file to improve performance. PKZIPz will automatically process 3420 reel to reel tape in this way to accelerate the copying process. By manually defining //ARCHTEMP DD in the job, this temporary dataset can also be passed to subsequent PKUNZIP steps for better performance. The use of this method requires that the size of the temporary archive be equal to or larger than the archive.
As temporary storage for file control information, including SORT work files.
When a high volume of dataset names is encountered during catalog filename selection and archive directory parsing, informational records may be written to work files for processing according to the memory controls provided in the job. Additionally, these temporary files are used for sort/merge processing for filename matching.
“New” ZIP Archive
When ZIP processing begins, PKZIPz creates a new ZIP archive that is the modified, or “after”, version of the old archive. The (modified) name of the old archive and specified allocation information of the old archive is automatically transferred to the new archive. After the update process completes, the old archive is deleted. If the new output archive allocation fails, PKZIPz will terminate, leaving the old input archive intact.
Temporarily, the new ZIP archive will keep the same name as the old ZIP archive, as named in the ARCHIVE command, except that the last part of the data set name will be replaced by a unique eight-character name. If the new archive is a member of a PDS or PDSE, this unique name acts as the member name.
295
12 Processing with GZIP
What Is GZIP?
GNU Zip is a different standard for handling compressed file data in an archive. Support for the GZIP standard can be found in various utilities for many platforms. This format is not compatible with PKZIPz archives; however, PKZIPz provides limited support for GZIP archives (Information regarding RFC processes for information interchange with regard to GZIP can be found at www.faqs.org/rfcs).
RFC 1951 is the specification that describes DEFLATE compressed data format that is to be used with GZIP archives. PKZIPz creates a compression stream that is compatible with this format.
RFC 1952 describes the GZIP archive format specifications. Differences from PKZIPz archives include:
All GZIP filenames must be represented in lower case.
Both binary and text data are supported by GZIP; however, the LATIN-1 translation table is the defined standard for EBCDIC/ASCII filename translation (ISO 8859-1).
Why Use GZIP?
GZIP may be useful when doing file exchanges to a platform only having a GZIP support utility.
Although GZIP has an almost limitless capacity, it has other significant limitations that make it less attractive than PKZIPz for most applications.
GZIP lacks a “directory” of the files contained within it. In addition, files contained within a GZIP archive can only be found in a serial fashion. (GZIP and ZIP have different nomenclature. Whereas a ZIP archive stores “files”, these data entities are known as “members” in a GZIP archive.)
The file information controls provided in GZIP archives cannot be fully reported on until the entire data stream is decompressed.
296
The GZIP format may not be recognized by other products providing ZIP archive support, and thereby restricts its cross-platform usefulness.
PKZIP and SecureZIP for z/OS Implementation Notes for GZIP
The DEFLATE compression algorithm used in GZIP is similar to the compression logic used in PKZIPz archives. The archive format is compatible with GZIP processes running on other platforms, although extensions provided by PKZIPz may not be supported by other utilities.
The standard GZIP archive format maintains a header entry at the beginning that describes the name of the file and a timestamp. A CRC integrity value is also maintained, however, this value is stored at the end of the file along with the original size of the input file.
GZIP Restrictions
The PKZIPz implementation for GZIP is restricted to 1 file within an archive. For this reason, only the ADD Action for a new archive is supported. Attempting to FRESHEN an existing file within an archive, adding additional files, or deleting a file from an archive should not be attempted.
Only the first file in a GZIP archive from another platform will be processed by UNZIP processing. For this reason, when creating GZIP archives on other platforms with MVS as the target system, only place one file in each GZIP archive file.
An existing archive must be processed in accordance with its archive type, such as, PKZIPz or GZIP. For example, an existing PKZIPz archive cannot have GZIP data appended to it. A message will be issued and processing will be terminated if this rule is not followed.
VIEW processing will not report the CRC or file size information because of the way GZIP archives hold the information.
COMPRESSION_LEVEL(STORE) is not part of the GZIP standard, and is therefore ignored by the compression engine.
The GZIP standard does not support strong encryption.
The GZIP standard does not support digital signatures.
GZIP Extensions As a proprietary extension, standard (96 bit) password encryption support is provided
beyond the RFC standard.
File attributes can be stored in the GZIP archive (just as they are in a PKZIPz archive) so that the file can be reconstructed during EXTRACT processing.
Filename control commands may be used—for example, ZIPPED_DSN. Lower-case translation of the resulting name is done to conform to GZIP requirements.
During EXTRACT processing, if the GZIP archive does not contain a file name (not required by GZIP specifications), then a filename is constructed with a low-level qualifier (or PDS/PDSE member name) of “GZOUT” by using the input archive name as
297
the base. This pseudo-name is then processed by filename-modifying commands such as UNZIPPED_DSN. (See also GZIP_SUFFIX in Chapter 10.
Although the default specification for GZIP processing is to handle data as BINARY, PKZIPz will use the DATA_TYPE command with DETECT or TEXT processing.
Although MULTI_THREAD_LIMIT is ignored for GZIP processing (because only one file can be compressed), multi-tasking is still performed for input file reads, data compression, and archive file writes to maximize processing throughput.
Although the GZIP standard does not support directory levels in the filename, many products (including PKZIPz) support this as an extension.
Although the timestamp in the archive is in UNIX-format and is by specification to be UTC, PKZIPz honors the TIMESTAMP command.
Processing GZIP Archives In general, a GZIP archive must be processed only in GZIP mode and with only one GZIP “member.” When creating a GZIP archive, specify GZIP in the command stream (or use a defaults module with the GZIP value set). UNZIP processing in PKZIPz automatically detects the GZIP header and processes accordingly.
If zipping a file for transport to another platform that does not support the extensions provided by PKZIPz, use commands to nullify those extensions—for example, NOATTRIB, NOPATH.
298
13 Using the ISPF Interface
Getting Started with the ISPF Interface
When the PKZIPz ISPF interface is started for the first time, the Configuration Menu displays. On subsequent use, the first display is the Main Menu. An example of this menu is shown below. From this panel the desired function can be selected by entering the letter associated with that function.
To display the help information, press PF1 from any panel in the ISPF interface and the help panel for that function is displayed.
To end the PKZIPz ISPF session, press PF3 or enter “X” while the main menu is displayed.
SecureZIP Version 9.0 Option ===> C Config Modify Run-time Configuration Settings ZD Zip Defaults Modify Default ZIP Command Settings UD Unzip Defaults Modify Default UNZIP Command Settings U Unzip Decompress, Decrypt, Authenticate File(s) in an Archive V View Display the Contents of a Zip Archive Z Zip Compress, Encrypt, Sign File(s) into a Zip Archive S Sysprint Browse Log of Last Foreground Execution M Messages Message ID lookup A Administration Administration Services and Reference Information For HELP Press PF1 Release Date: 06/26/2006 07.22 LVL(0)
299
Configuration (Option ‘C’)
The PKZIPz ISPF interface requires configuration information to function correctly in the user environment. Upon initial use of the ISPF interface, the Configuration Menu is displayed regardless of the option selected. The following is an example of the Menu.
SecureZIP Runtime Configuration Command ===> More: + Execution load library: '.LOAD' Initial Execution Default Command Settings Defaults module.....: ACZDFLT (ACZDFLT) ZIP processing......: 'PKWARE.MVS.INSTLIB(CMDZIP)' UNZIP processing....: 'PKWARE.MVS.INSTLIB(CMDUNZIP)' Foreground Processing Controls Use TSO Prefix : N (Y/N) Lowest Acceptable RC: 4 (0,4,8) SYSPRINT Allocation Type : CYLS (BLKS,TRKS,CYLS) Primary : 5 Secondary : 5 Batch Job Card information //JOBNAME JOB 'INFO',CLASS=A,REGION=8M, // MSGCLASS=H,MSGLEVEL=(1,1),NOTIFY=&SYSUID //* To EXIT Press PF3 For HELP Press PF1
The configuration panel is shown above. There are several configuration data fields on this panel:
Field Description
Load Library The library that contains the executable code for SecureZIP for z/OS. The default is the installed load library.
Defaults Module The module listed here is used as the installed defaults for all PKZIP or PKUNZIP jobs generated by ISPF. The default module is ACZDFLT.
Defaults Files The files that contain any overrides to the installed defaults. There is one for ZIP processing and one for UNZIP processing. The default file names are dsnhlq.INSTLIB(CMDZIP) and dsnhlq.INSTLIB(CMDUNZIP) (where dsnhlq is the high level qualifier specified during installation).
TSO Prefix This field controls the use of the TSO prefix. Specify ‘Y’ to have the value of the TSO prefix appended to all unquoted data set names as the high level qualifier. If NOPREFIX is specified in the TSO PROFILE, then the value of this field is ignored.
Lowest Acceptable RC
This field controls the display of the generated output of a foreground execution. If the return code of the execution is greater than the number entered in this field, then the output is automatically displayed after the run.
Sysprint Allocation Information used to set the default size for the SYSPRINT (output) file.
Job Card The default job card to be used in all batch jobs generated by the SecureZIP for z/OS ISPF interface.
300
Defaults (Options ZD and UD)
As explained previously, PKZIPz defaults are provided at installation time. These are reflected in the table displayed by options ZD and UD. Option ZD displays the defaults in place for ZIP processing. Option UD displays the UNZIP defaults.
When either option ZD or UD is selected, the defaults are displayed in a scrollable table. An example is shown below. The defaults can be changed and will override the installed defaults for the remainder of this ISPF PKZIPz session or until a LOAD or RESET command is entered. Use the CANCEL command to return to the calling function without processing the changes. All changes made prior to the cancel remain in effect until RESET or until the ISPF session is terminated.
SecureZIP for z/OS 9.0 Zip Defaults Row 1 to 13 of 184 COMMAND ===> SCROLL ===> PAGE Make changes to option value(s) and Press ENTER and/or enter command. EXIT (PF3) - Return and process changes SAVE - Save changes in data set (RES)ET - Restore original defaults LOAD - Load from a saved file (CAN)CEL - Return - DO NOT Process DISP - Display Current Changes (L)OCATE - Locate Option / - Select option for update / Option Name Option Value --------------------------- ----------------------------------- ACTION ADD ARCHIVE_BLKSIZE DYNAMIC ARCHIVE_COMMENT SecureZIP for z/OS by PKWARE Inc. ARCHIVE_DATACLASS ARCHIVE_DIR_BLOCKS 52 ARCHIVE_DSN ARCHIVE_DSORG PS ARCHIVE_INFILE ARCHIN ARCHIVE_LRECL DYNAMIC ARCHIVE_MGMTCLASS ARCHIVE_OUTFILE ARCHOUT ARCHIVE_RECFM U
Use PF7 and PF8 or the UP and DOWN commands to scroll the table display.
Only the first 34 characters of an option value is displayed. If the option value exceeds 34 characters, then a ‘+’ is displayed at the end of those 34 characters indicating that the option value is longer than the display field. The entire length of the field is maintained when the changes are processed. Only the display is truncated.
301
Primary Commands The following table lists the commands that can be entered on the Defaults panel.
Command Description
CANCEL This command allows you to return from the default options display without generating. All changes made prior to the CANCEL command will remain. To change them back to the original defaults, use the RESET command as explained above.
DISP This command gathers all the changes to the default options and format a scrollable display showing the options, their current value and the origin of the change. The origin can be DS (loaded from a dataset), CD (changed on the defaults panel), or AV (changed by the Advanced Option feature on the ZIP and UNZIP options—explained later in this chapter). An example of this display is shown below.
EXIT End the defaults display and return to the SecureZIP for z/OS main menu. Pressing PF3 has the same results.
LOAD This command loads default settings that were previously saved in a data set using the SAVE command. You are prompted to enter the data set name and member name. First a RESET is done to clear any previously changed defaults and then the default option values saved in the data set entered are loaded and the displayed table is updated. Any options changed by the LOAD are flagged with the string ‘**Loaded**’. These defaults will remain in effect until this SecureZIP for z/OS session is ended or the RESET command is entered.
LOCATE This command positions the table display to a particular default option or to a default option beginning with a certain string. For example, by entering LOCATE C the table display will be positioned so that the first default option beginning with the letter ‘C’ will be the first line displayed. This command can be truncated to LOC or L.
RESET This command resets any changes made using this option and restore the defaults as they were installed and/or modified by the systems programmer. This command can be truncated to RES.
SAVE This command prompts you for a data set name and member. Then any changes made to the defaults subsequent to the SAVE command are written to the data set entered. That data set can then be reloaded using the LOAD command explained below.
The Changed Zip Defaults panel looks like this:
Display of Changed Zip Defaults Row 1 to 4 of 4 COMMAND ===> SCROLL ===> PAGE The following options have been changed from the original defaults. Source of changes: DS - Loaded from data set CD - Changed default panel AV - Zip or UnZip Advanced options / Option Name Current Option Value Origin --------------------------- ----------------------------------- ------------- MEMORY_MODEL LARGE AV ACTION FRESHEN DS LOGGING_LEVEL VERBOSE DS ARCHIVE_DSORG PE CD
302
Changing Default Options The default option values vary depending on the option being changed. There are seven types of options: A Y/N option, a numeric option, an EBCDIC character, a data set name, clear text, a list of volumes, and an option list. Each of these are explained below. An option of any type must be selected for update by first typing a ‘/’ in the field at the beginning of line where the desired option is displayed and pressing “Enter”. After the option is selected and its type is determined, then the update proceeds as explained below.
Option Type Description
Y/N The value of the selected YES/NO option is toggled. If it is currently a ‘Y’, then it is made a ‘N’ and vice versa.
Numeric When an option with a numeric value is selected, then a ‘pop-up’ panel is displayed where the desired numerical value can be entered.
EBCDIC When an option value is a single EBCDIC character, a ‘pop-up’ panel is displayed where the desired character can be entered.
Data set Name If the value of an option is a data set name, then a ‘pop-up’ panel is displayed allowing the name of a data set to be entered. The data set name can be in the form of MY.DATA.SET.NAME or MY.DATA.SET.NAME(MEMBER).
Text If an option value is character or text information, then a ‘pop-up’ panel is displayed allowing the desired text to be entered. Text can be up to 255 characters depending on the option.
Volume List Some option values are lists of volume serial numbers. Selecting an option of this type will cause a ‘pop-up’ panel to display where from 1 to 31 volume serial numbers can be entered.
Option List Several options have a list of valid values. When an option of this type is selected for update, a scrollable panel is displayed showing all of the valid values for that option. The desired value can then be selected by placing a ‘/’ beside the desired value.
Changes entered for the updates above are identified on the panel by the string ‘**Changed**.
Including Changed Defaults
Any ZIP and/or UNZIP default options changed using this PKZIPz option are included in every corresponding ZIP and/or UNZIP foreground and batch job generated during this PKZIPz ISPF session. A PKZIPz ISPF session is defined from the time the main menu is displayed until it is exited. The proper commands are generated and included in the appropriate input stream.
View Archive (Option ‘V’)
This option is used to view information about the files contained in a zip archive. The information is formatted in a scrollable table and displayed on a panel. The table can be scrolled ‘UP’, ‘DOWN’, ‘LEFT’, and ‘RIGHT’ using the commands (or PF7, PF8, PF10, and PF11). The information displayed about each archived file spans three panels. Scrolling LEFT or RIGHT displays each panel in turn and the associated archived file information. The initial panel for option ‘V’ is shown below. There are also several line commands that can be used to browse, view, extract, display file information, or delete the selected file.
303
0020 SecureZIP View Archive Command ===> Enter name of archive to be viewed: Archive Name . .: 'FPD.TEST.VIEWFILE.ZIP' Dataset Filter .: Security options: Security required. : N ( Y - To Display Security Options Dialogue) Enter VIEW Options: View Type . .: V ( V - View, D - Detail, B - Brief, S - Scan Sort Output : N ( Y - Yes, N - No) Sort Field . : ( D - Date, N - Name, O - Offset, P - Percent, S - Size) Sort Order . : ( A - Ascending, D - Descending) Processing Mode. : F ( F - Foreground, B - Batch) Batch JCL Status : C ( C - New Dataset, A - Add to existing Dataset) Additional Commands: To EXIT Press PF3 or enter X For HELP Press PF1
Setting VIEW Options The panel shown above is used to specify options for the VIEW operation. The individual fields are given in the following table:
Field Description
Archive Name Enter the name of the archive to be viewed. It can be in the form of DATA.SET.NAME or DATA.SET.NAME(MBR). Standard data set naming conventions apply. Place the data set name in single quotes (‘…’) to prevent using the TSO prefix as the first qualifier. This option can be turned off using the Configuration option explained earlier.
Data set Filter This field is used to specify a wildcard type filter used to limit the number of data sets displayed. If this field is entered, only those data sets matching the filter will be displayed on the VIEW information panels.
Security required If authentication is required for this archive, select ‘Y”. Additional panels will guide you through the security requirements.
View Type If a 'V' is selected, then the files within the selected archive are displayed on the scrollable panels shown within this chapter. The information displayed on the panels is obtained from a ACTION(VIEWDETAIL) command. If a 'B' is selected then a ACTION(VIEWBRIEF) command is executed and the output print file is displayed using ISPF browse. The ‘D’ option generates the same command as the ‘V’ option, but the output is browsed instead of being displayed in an ISPF table.
Sort Output The displayed file list can be sorted prior to being displayed by entering a 'Y' in this field. When this field is a ‘Y’ then the following two fields are used to specify sort options.
Sort Field This field is used to specify which display fields to sort on. Enter a ‘D’, ‘N’, ‘O’, ‘P’, or ‘S’ to sort on date, file name, offset, percent compressed, and compressed size, respectively.
Sort Order Specify ‘A’ for ascending or ‘D’ for descending.
Processing Mode Specifying a 'F' in this field will run the view job as a foreground task. Specifying a 'B' will build JCL for a batch job. The JCL will be displayed so it can reviewed and/or modified before submission. Only the foreground task will display the output on the panels.
304
Field Description
Batch JCL Status Specifying a 'C' in this field creates a new job to be submitted in a batch run. Specifying a 'A' in this field adds generated JCL to an already existing file to be submitted as multiple steps in one job.
By using first a ‘C’ option on one panel then a series of other panls using the ‘A’ option, you can generate a series of steps to process as one job. For example, you may want to build a ZIP archive and then View that archive. By using this feature, you can generate the ZIP JCL from the Z Option and then go to the View panel and generate the View JCL where you will then submit the batch job.
To exit the VIEW operation and return to the main menu, press PF3. Help for the VIEW function can be obtained by pressing PF1. Pressing PF3 on any of the information display panels will return to the main VIEW panel.
SecureZIP View Archive Row 1 to 7 of 48 Command ===> SCROLL ===> CSR Name of Archive : 'SECZIP.TEST.ZIP' Primary commands: LOCATE to position list or SORT to sort list. Enter line command or '/' for list of valid line commands. Cmd File Name Zipped Zipped Unzipped Comp Type Volume(s) Message Date/Time Size Size Ratio ---------------- ------ ------ ----- ---- ------- _ PKZIP/TEST/PDS/DELCSI 1/24/2006 10:42 456 3281 86% TEXT TSO002 _ + PKZIP/TEST/PDS/DELLINK 1/24/2006 10:42 8010 85855 90% TEXT TSO002 _ PKZIP/TEST/PDS/DELNUC 1/24/2006 10:42 8010 85855 90% TEXT TSO002 _ + PKZIP/TEST/PDS/DELNVSM 1/24/2006 10:42 365 1477 75% TEXT TSO002+ _ PKZIP/TEST/PDS/DELUCAT 1/24/2006 10:42 314 1067 70% TEXT TSO002+ _ PKZIP/TEST/PDS/DELVSAM 1/24/2006 10:42 278 1067 73% TEXT TSO002 _ PKZIP/TEST/PDS/DIAGBCS 1/24/2006 10:42 230 739 68% TEXT TSO002
SecureZIP View Archive Row 1 to 7 of 48 Command ===> SCROLL ===> CSR Name of Archive : 'SECZIP.TEST.ZIP' Primary commands: LOCATE to position list or SORT to sort list. Enter line command or '/' for list of valid line commands. Press PF1 for HELP. Cmd File Name Ds Rec Record Block Space Date Last Org Fmt Size Size Prim Sec Dir Unit Created Referenced ---- --- ------ ------ ---- --- --- ---- ---------- ---------- _ PKZIP/TEST/PDS/DELCSI PO FB 80 27920 5 2 200 CYL 2006/01/24 2006/01/24 _ PKZIP/TEST/PDS/DELLINK PO FB 80 27920 5 2 200 CYL 2006/01/24 2006/01/24 _ PKZIP/TEST/PDS/DELNUC PO FB 80 27920 5 2 200 CYL 2006/01/24 2006/01/24 _ PKZIP/TEST/PDS/DELNVSM PO FB 80 27920 5 2 200 CYL 2006/01/24 2006/01/24 _ PKZIP/TEST/PDS/DELUCAT
305
PO FB 80 27920 5 2 200 CYL 2006/01/24 2006/01/24 _ PKZIP/TEST/PDS/DELVSAM PO FB 80 27920 5 2 200 CYL 2006/01/24 2006/01/24 _ PKZIP/TEST/PDS/DIAGBCS PO FB 80 27920 5 2 200 CYL 2006/01/24 2006/01/24
SecureZIP View Archive Row 1 to 7 of 48 Command ===> SCROLL ===> CSR Name of Archive : 'SECZIP.TEST.ZIP' Primary commands: LOCATE to position list or SORT to sort list. Enter line command or '/' for list of valid line commands. Press PF1 for HELP. Cmd File Name Compression CRC Compressed Needed to Method By Extract ----------- -------- ------------------ --------------------- _ PKZIP/TEST/PDS/DELCSI DEFLATE BA6AB353 PK ZSERIES 9.0 ZipSpec 2.0 _ PKZIP/TEST/PDS/DELLINK DEFLATE 2F2AA610 PK ZSERIES 9.0 ZipSpec 2.0 _ PKZIP/TEST/PDS/DELNUC DEFLATE 2F2AA610 PK ZSERIES 9.0 ZipSpec 2.0 _ PKZIP/TEST/PDS/DELNVSM DEFLATE 62E3B570 PK ZSERIES 9.0 ZipSpec 2.0 _ PKZIP/TEST/PDS/DELUCAT DEFLATE FF65B6F2 PK ZSERIES 9.0 ZipSpec 2.0 _ PKZIP/TEST/PDS/DELVSAM DEFLATE C3593401 PK ZSERIES 9.0 ZipSpec 2.0 _ PKZIP/TEST/PDS/DIAGBCS DEFLATE 822BD61C PK ZSERIES 9.0 ZipSpec 2.0
Primary Commands The primary command UP, DOWN, LEFT, and RIGHT can be entered to control the scrolling. Also the LOCATE command can be entered to position the list of files displayed to a file name beginning with the string specified. The display can also be sorted on several fields.
The format of the sort command is:
306
SORT <field> <order>
The sort field (<field>) can be one of the following:
NAME File name.
DATE Date zipped.
TIME Time zipped.
ZSIZE Compressed size.
USIZE Uncompressed size.
RATIO Compression ratio.
CREATED File creation date
REF Last date file referenced
The sort order (<order>) can be either:
A Ascending order
D Descending order
For example, to sort the display on zipped size beginning with the largest item, enter:
SORT ZSIZE D
Line Commands Once the list of files is displayed, there are several line commands that may be entered. They are entered in the left-most field next to the desired file. To execute the line commands, press “Enter”. Multiple selections are allowed and will be processed in succession. To select from a list of valid commands, enter a ‘/’ for the line command. The panel below shows the View Line Commands.
SecureZIP View Line Commands Command ==> Data Set: 'FPD.TEST.VIEWFILE.ZIP' Action: B - Browse File PV - Preview n Lines of File BB - Browse Binary File D - Delete File BT - Browse Text File I - Display File Information V - View File ID - Information Details VB - View Binary File SI - Display File Signers VT - View Text File X - Extract File XO - Extract with Overwrite Select an action and press ENTER to process Press PF3 to return to data set list.
You can select the desired action by typing a ‘/’ next to it. The valid commands are given in the following table.
307
Command Description
B-Browse The selected file is extracted to a temporary file which is then displayed using ISPF browse. This option does not work for UNIX files with lower case file names. If the selected file is a VSAM file, then the file is browsed as a sequential file.
BT-Browse Text Same as the browse command above except this will generate a DATA_TYPE(TEXT) command for the extract to the temporary file. This is used when the file comes from another platform and/or has incomplete attributes.
BB-Browse Binary Same as the browse command above except this will generate a DATA_TYPE(BINARY) command for the extract to the temporary file. This is used when the file comes from another platform and/or has incomplete attributes.
D-Delete The selected file is deleted from the archive file. A confirmation panel will be displayed to confirm the delete.
I-Info This option displays detailed information about the selected file. This display is similar to the 'I' command given on the Data set List (3.4) display.
SI-Display File Signers This command will display the detailed information on who signed this file.
PV-Preview Extract This command will display the first n lines of an archived file. This option can be used to view a portion of a large file without extracting the entire file. A prompt will request the number of lines to display.
V-View The selected file is extracted to a temporary file which is then displayed using ISPF view. This option does not work for VSAM files or for UNIX type files with lower case file names. Standard ISPF View commands (such as CREATE) can be used to make a copy of the file being viewed.
VT-View Text Same as the view command above except this will generate a DATA_TYPE(TEXT) command for the extract to the temporary file. This is used when the file comes from another platform and/or has incomplete attributes.
VB-View Binary Same as the browse command above except this will generate a DATA_TYPE(BINARY) command for the extract to the temporary file. This is used when the file comes from another platform and/or has incomplete attributes.
X-Extract The selected file is extracted from the archive file.
XO-Extract with overwrite The selected file is extracted from the archive file and will overwrite an existing file with the same name. Same as the ‘X’ command except the OUTFILE_OVERWRITE(Y) command is generated.
Note: Each time a zipped file is selected for browsing or viewing, a temporary file is created. Depending on the size of the unzipped file, the temporary file may be quite large. If you are running under SMS control, SMS will attempt to find the necessary space for the large file and your terminal will be locked during that period of time.
Display Fields There are several fields of information displayed for each file in the archive. Each field is explained in the table below.
308
Field Description
File Name The file name field contains the name(s) of the file(s) contained in the archive. This name can contain both upper and lower case letters. This is the only field that is repeated on each display panel. If a ‘+’ is displayed immediately in front of the file name this indicates that that file is encrypted and any operation on that file will require a password.
Date/Time Zipped The field contains the data and time that the file was compressed and added to the archive.
Zipped Size This field contains the number of bytes the file contains after it was compressed. If the file attributes are incomplete or if the file was compressed in GZIP format, this field will contain ‘N/A’.
Unzipped Size This field contains the number of bytes the file contained before it was compressed. If the file attributes are incomplete or if the file was compressed in GZIP format, then this field will contain ‘N/A’.
Compression Ratio This field contains the ratio between uncompressed size and compressed size. It provides a measure of the degree of compression.
File Type This field indicates the type of data contained in the compressed file. It can be text (TEXT) or binary (BIN).
Volume This field indicates the volume from which the compressed file came. If it is a multi-volume file, only the first volume is displayed along with a plus sign (+) indicating there are additional volume(s).
Message This field is used to show the last line command executed against this file. The valid displays are '*Browsed', '*Viewed', '*Info', '*Unzip', and '*Delete'.
Dsorg This field displays the data set organization of the compressed file. Valid entries are ‘PS’ for a sequential file, ‘PO’ for a PDS, ‘VSAM’, and 'PDSE' for a PDS extended file.
Record Format Record format of the compressed file.
Record Size Record size of the file in bytes.
Block Size Block size of the file in bytes.
Primary Space Amount of primary space allocation.
Secondary Space Amount of secondary space allocation.
Allocation Units BLKS, TRKS, or CYLS.
Directory Blocks Number of directory blocks allocated.
Creation Date Date the file was created.
Last-Referenced Date Date the file was last referenced.
Compression Method Method used to compress the file.
Cyclic Redundancy Check A 32-bit field used to ensure integrity of the file. This field is calculated during compression. It is re-calculated when the file is decompressed and that value is checked against the original value.
Compressed by Program used to compress file.
Needed to Extract The ZIP Specification level required to extract the file. The number listed is not a version of the SecureZIP for z/OS program but rather a version of the ZIP file format.
309
Using Security The panels shown below are used to specify options for archive authentication.
| SecureZIP VIEW Processing | | Command ===> | | More: | | Security options: | | Encrypt Facilities : IBMHARDWARE,IBMSOFTWARE,SECUREZIP / for list | | Hashing Facilities : IBMHARDWARE,SECUREZIP / for list | | | | Password access : N ( Y Decrypt Directory) Display Typed Password: | | ------------------------------------------------------------------------- | | SecureZIP certificate-based operations. | | | | Certificate Decryption: | | File Name Encryption: N ( Y - Digital Certificate Directory Decryption) | | Recipients : N ( Y - Digital Certificate Directory Decryption) | | | | Archive Authentication | | Archive : N ( Y - Authenticate Archive Directory signature) | | Validation Policy: Y Trusted Y Expired Y Revoked Y Tampercheck | | | | ------------------------------------------------------------------------- | | Reporting: | | Certificate Report : Y ( Y - Recipients show in SYSPRINT) | +-----------------------------------------------------------------------------+ | SecureZIP Archive Authentication | | Command ===> | | Archive File Information: | | Archive Name : 'FPD.TEST.VIEWFILE.ZIP' | | Specific signers : N ( Y - Verify against a list of signatories) | | ( N - A generic -AUTHCHK(ARCHIVE)) | | | | / Local Store Data Base Profile | | DB Profile > 'PKWARE.MVS.PROFILES(DBPSTD)' | | List the signing certificates to be used if Specific signers=Y above. | | / Edit a file containing a set of -AUTHCHK commands. | | S Search the Local Certificate Store to build a list | | Archive Signers List: 'PKWARE.MVS.CERTSTOR.PROFILES($AUTHARC)' | | | | Individual Signers: An -AUTHCHK() request will be built | | for each of the following requests. | | 1. | | 2. | | 3. | | 4. | | 5. | | |
Archive Authenticated The panels shown below display “Authenticated” and the name of the signer if you selected to authenticate the archive during “View” processing.Archive Signed
SecureZIP View Archive Authenticated Command ===> SCROLL ===> CSR Name of Archive : 'FPD.TEST.VIEWFILE.ZIP' Archive was digitally signed by PKWARE Test1; Primary commands: LOCATE to position list or SORT to sort list. Enter line command or '/' for list of valid line commands. Press PF1 for HELP.
310
Cmd FileName Zipped Zipped Unzipped Comp Type Volume(s) Message Date/Time Size Size Ratio ---------------- ------ ------ ----- ---- ------- S FPD/TEST/ARC1 2/01/2006 16:24 1248 1383 9% BIN FPD001 FPD/TEST 2/01/2006 16:24 284 560 49% BIN FPD001 FPD/TEST/ARC2 2/01/2006 16:24 1248 1383 9% BIN FPD001 FPD/TEST/ARC3 2/01/2006 16:24 1248 1383 9% BIN FPD001 FPD/TEST/ARC5 2/01/2006 16:24 2155 3925 45% BIN FPD002 FPD/TEST/ARC4 2/01/2006 16:24 2116 2543 16% BIN FPD002
The panels shown below display the message “Archive was digitally signed”, without specific information on the signer, if you do not request authentication and the archive is signed.
SecureZIP View Archive Row 1 of 10 Command ===> SCROLL ===> CSR Name of Archive : 'FPD.TEST.VIEWFILE.ZIP' Archive was digitally signed Primary commands: LOCATE to position list or SORT to sort list. Enter line command or '/' for list of valid line commands. Press PF1 for HELP. Cmd FileName Zipped Zipped Unzipped Comp Type Volume(s) Message Date/Time Size Size Ratio ---------------- ------ ------ ----- ---- ------- S FPD/TEST/ARC1 2/01/2006 16:24 1248 1383 9% BIN FPD001 FPD/TEST 2/01/2006 16:24 284 560 49% BIN FPD001 FPD/TEST/ARC2 2/01/2006 16:24 1248 1383 9% BIN FPD001 FPD/TEST/ARC3 2/01/2006 16:24 1248 1383 9% BIN FPD001 FPD/TEST/ARC5 2/01/2006 16:24 2155 3925 45% BIN FPD002 FPD/TEST/ARC4 2/01/2006 16:24 2116 2543 16% BIN FPD002
File Signers The panel shown below lists all of the file signers of the displayed file.
SecureZIP File Signers Option ===> File: FPD/TEST was digitally signed by: *************************************************************************** PKWARE Test1;[email protected];00 PKWARE Test2;[email protected];00 PKWARE Test3;[email protected];03 PKWARE Test4;[email protected];04
311
Zip (Option ‘Z’)
This option is used when a file or multiple files are to be compressed and added to a zip archive. You must enter the name of a zip archive. This file can be a new file or an existing file. Additionally, you must indicate what file(s) to compress, indicate the name of the files in the archive, and select the desired processing options. The initial panel displayed when this option is selected is shown below.
SecureZIP ZIP Processing Command ===> Archive File Information: File Name : 'FPD.MVS.SPKZLIBS.DEC31.ZIP' File Type : 1 ( 1 = SEQ, 2 = PDS, 3 = VSAM, 4= PDSE) More Attributes : N ( Y - Yes, N - Take Defaults) Zip file information: File to compress : 'PKWARE.MVS.SPKZ*' Zipped DSN : Format : Y ( B -Binary T -Text D -Detect BV -Binary-Variable) More Files : N ( Y - Enter additional file names, N - None) Security options: Security required : N ( Y - To Display Security Options Dialogue) Processing options: Simulation Mode : N ( Y - Test file selection, N - Normal Processing) Zip Function : A ( A - Add, F - Freshen, U - Update, D - Delete) Processing Mode : B ( F - Foreground, B - Batch) Batch JCL Status : C ( C - New Dataset, A - Add to existing Dataset) Advanced Options : N ( Y - Change Defaults, N - None) Enter VIEW on command line to VIEW archive To EXIT Press PF3 or enter X For HELP Press PF1
Based upon the panel input, commands are built and included in the compress job’s input (SYSIN) stream. The commands generated are fully explained in the commands chapter of this manual. The individual panel fields and their affect on processing are described in the following table:
Field Description
Archive Name Enter the name of the archive file. It can be in the form of DATA.SET.NAME or DATA.SET.NAME(MBR). Standard data set naming conventions apply. Place the data set name in single quotes (‘…’) to prevent using the TSO prefix as the first qualifier. This option can be turned off using the Configuration option explained earlier. This file can be a new or an existing file.
File Type If the archive file entered above is a new file, this field is used to specify what type of archive is desired. Valid entries are ‘1’ for a sequential file, ‘2’ for a PDS file, ‘3’ for a VSAM archive, and ‘4’ for a PDS extended archive. The default is a sequential file.
More Attributes When the archive file entered above is a new file and this field is set to ‘Y’, then a panel is displayed where additional allocation specifications for the archive file can be entered.
File to Compress This field is used to specify what file(s) are to be compressed and added to the archive file. A fully qualified name can be entered or standard wildcards can be used to select multiple files. See Chapter 7 for rules on file selection.
Zipped DSN This field is used to give the compressed file a new name in the archive file. It generates a ZIPPED_DSN command. That command is explained in Chapter 10.
312
Field Description
Encryption A ‘Y’ in this field indicates that the file to be compressed should be encrypted. This will cause a panel to be displayed requesting that you enter a 1-250 character password to be associated with the compressed file. This field is initialized to an ‘N’.
View Typed Password Enter a ‘Y’ or ‘N’. A ‘Y’ indicates that the password will be displayed while you enter it. This field is initialized to ‘N’.
Format This field indicates the file type of the file to be compressed. Valid entries are ‘B’ for binary, ‘T’ for text, ‘D’ for detect, and ‘BV’ for binary-variable. The value entered will be used to construct a DATA_TYPE command. If the value entered is ‘BV’ then a SAVE_LRECL(Y) command is also generated.
More Files If more file selection entries are desired, enter a ‘Y’ in this field. Another panel will be displayed where up to 10 additional file specifications can be entered.
Security required If encryption or authentication is required for this archive or the files within the archive select ‘Y’. Additional panels will guide you through the security requirements.
Simulation Mode Specifying a 'Y' in this field will run the compress job in simulation mode. A SIMULATE(Y) command is added to the input stream. This allows file selection and renaming operations to be verified before files are actually written. No file(s) are actually added to the archive file.
Zip Function This field will determine the type of ACTION command that will be generated. Valid entries are: ‘A’ for ACTION(ADD), ‘F’ for ACTION(FRESHEN), ‘U’ for ACTION(UPDATE), and ‘D’ for ACTION(DELETE).
Processing Mode Specifying a ‘F’ in this field will run the compress as a foreground task. Specifying a ‘B’ will build JCL for a batch job. The JCL will be displayed so it can reviewed and/or modified before submission. The job is submitted by the TSO SUBMIT command.
Batch JCL Status Specifying a ‘C’ in this field will create a new job to be submitted in a batch run. Specifying a ‘A’ in this field will continue adding generated JCL to an already existing file to be submitted as multiple steps in one job. Using first a ‘C’ option on one panel then a series of other panls using the ‘A’ option you may generate a series of steps to process as one job. For example, you may want to build a ZIP archive and then View that archive. By using this feature you can generate the ZIP JCL from the Z Option and then go to the View panel and generate the View JCL where you will then submit the batch job.
Advanced Options Specifying a ‘Y’ in this field will display the current defaults for zip processing and allow them to be changed and included as commands in this extract. This is the same process described for Option ‘ZD’ earlier. As the options are changed they are flagged with the string ‘**Adv Options**’. This field is initialized to a ‘N’.
After all the fields have been entered, press “Enter” to process the panel and build the compress job. To display the ZIP help information, press PF1. Enter ‘VIEW’ as a primary command to view the current contents of the specified archive file. This VIEW option is explained above under Option ‘V’.
SecureZIP ZIP Processing +-----------------------------------------------------------------------------+ | SecureZIP ZIP Processing | | Command ===> | | More: | | Security options: | | Encrypt Facilities : IBMHARDWARE,IBMSOFTWARE,SECUREZIP / for list | | Hashing Facilities : IBMHARDWARE,SECUREZIP / for list | | | | Encryption: |
313
| Password protect : N ( Y - Use Passwords) : N ( Y - View typed pwd) | | Algorithm : BSAFE_AES256 / for selection list | | Filename Encryption: N ( Y - Encrypt file names in the Archive) | | ------------------------------------------------------------------------- | | SecureZIP certificate-based operations. (Page down for all options) | | | | Certificate Encryption: | | Recipients : N ( Y - Digital Certificate Encryption) | | Validation Policy: Y Trusted Y Expired Y Revoked | | | | Signing: | | Archive : N ( Y - Sign Archive Central Directory) | | Files : N ( Y - Sign Files) | | Hash Algorithm : SHA-1 (MD5, SHA-1) | | Validation Policy: Y Trusted Y Expired Y Revoked | | | | Authentication: | | Archive : N ( Y - Authenticate Archive Directory) | | Validation Policy: Y Trusted Y Expired Y Revoked Y Tampercheck | | ------------------------------------------------------------------------- | | Reporting: | | Certificate Report : Y ( Y - Verbose certificate selection info) | | | +-----------------------------------------------------------------------------+
Using Security The panel shown above is used to specify options for the password protection, filename encryption, recipient based encryption, signing for files and the archive, and authentication if this is an update to an existing archive.
Enter ‘Y’ to select an option.
+---------------------------------------------------------------------------+ | SecureZIP Password Encryption | | Command ==> | | | | To encrypt file(s), enter a password and select an algorithm | | | | Data Set Name: | | FPD.JCLZ.CNTL | | | | Password (up to 250 characters): | | ....5...10....5...20....5...30....5...40....5...50....5...60....5...70 | | | | | | | | Re-enter password: | | | | | | | | | | Press ENTER to continue, PF3 to terminate processing. | | | | | | | | | | | | ....5...10....5...20....5...30....5...40....5...50....5...60....5...70 | '---------------------------------------------------------------------------' To EXIT Press PF3 or enter X For HELP Press PF1
314
Select Password Protect The panel shown above is used to specify the password used to encrypt the file(s).
+-----------------------------------------------------------------------------+ | SecureZIP Encryption | | OPTION ===> | | More: | | | | Recipients | | | | / to Edit the profile used to satisfy DB: and LDAP: requests. | | DB Profile > 'PKWARE.MVS.PROFILES(DBPROF)' | | LDAP Profile> 'PKWARE.MVS.PROFILES(LDAPPROF)' | | | | / Edit a file containing a set of -RECIPIENT commands. | | S Search the Local Certificate Store to build a list | | M Data set member selection list | | Recipient List: 'PKWARE.MVS.PROFILES($RECIPX)' | | | | Individual Recipients: A -RECIPIENT() request will be built for each of | | of the following requests. | | 1. | | 2. | | 3. | | 4. | | 5. | | | +-----------------------------------------------------------------------------+
Select Recipients The panel shown above is used to specify the recipient certificates used to encrypt the files in the archive.
+-----------------------------------------------------------------------------+ | SecureZIP Authentication | | OPTION ===> | | | | Archive Signing | | | | / Local Store Profile | | DB Profile > 'PKWARE.MVS.PROFILES(DBPROF)' | | / Edit a file containing a set of -SIGN_ARCHIVE commands. | | S Search the Local Certificate Store to build a list | | M Data set member selection list | | Archive Signers List: 'PKWARE.MVS.CERTSTOR.PROFILES($SIGNARC)' | | | | Individual Signer: A -SIGN_ARCHIVE() request will be built | | for the following request. | | DB:CN=PKWARE TEST4,R,password=PKWARE | | | | Note: An archive can only contain a single signature. | | If an Individual Signer is used, the Archive Signer LIst is ignored. | | If an Archive Signer List is used, it must contain ONLY one entry | | | +-----------------------------------------------------------------------------+
315
Archive Signing The panel shown above is used to specify the certificates used to sign the archive for authentication.
| SecureZIP Authentication | | OPTION ===> | | | | File Signing | | | | / Local Store Profile | | DB Profile > 'PKWARE.MVS.PROFILES(DBPROF)' | | / Edit a file containing a set of -SIGN_FILES commands. | | S Search the Local Certificate Store to build a list | | M Data set member selection list | | File Signers List: 'PKWARE.MVS.CERTSTOR.PROFILES($SIGNFIL)' | | | | Individual Signers: A -SIGN_FILES() request will be built | | for each of the following requests. | | 1. | | 2. | | 3. | | 4. | | 5. | | | | Note: Sign Files requests are cumulative. All requests from the | | Sigh Files List and Individual Signers, will be included | | | +-----------------------------------------------------------------------------+
File Signing The panel shown above is used to specify the certificates used to sign the files for authentication.
+-----------------------------------------------------------------------------+ | SecureZIP Archive Authentication | | Command ===> | | Archive File Information: | | Archive Name : 'FPD.MVS.SPKZLIBS.DEC31.ZIP' | | Specific signers : N ( Y - Verify against a list of signatories) | | ( N - A generic -AUTHCHK(ARCHIVE)) | | | | / Local Store Data Base Profile | | DB Profile > 'PKWARE.MVS.PROFILES(DBPROF)' | | List the signing certificates to be used if Specific signers=Y above. | | / Edit a file containing a set of -AUTHCHK commands. | | S Search the Local Certificate Store to build a list | | M Data set member selection list | | Archive Signers List: 'PKWARE.MVS.PROFILES($AUTHARC)' | | | | Individual Signers: An -AUTHCHK() request will be built | | for each of the following requests. | | 1. DB:CN=PKWARE TEST4,PASSWORD=PKWARE | | 2. | | 3. | | 4. | | 5. | | | +-----------------------------------------------------------------------------+
316
Archive Authentication The panel shown above is used to specify the certificates used to authenticate the archive.
UNZIP (Option ‘U’)
This option allows the user to decompress or unzip one or more files that were previously compressed and stored in a zip archive. The user must enter the name of the archive, indicate what file(s) to decompress, and set any desired processing options. The initial panel displayed when this option is displayed is shown in Figure 9-5.
SecureZIP Extract Processing Command ===> Enter Archive from which file(s) are to be extracted: Archive Name . . . : 'FPD.TEST.SCREENS.ZIP' Enter Files to be extracted: File Selection . . : Rename to. . . . . : More Files . . . . : N ( Y - Enter additional file names, N - None) Security options: Security required. : N ( Y - To Display Security Options Dialogue) Enter processing options: Simulation Mode. . : N ( Y - Test file selection, N - Normal Processing) Integrity Check. . : N ( Y - Yes, N - No) Overwrite/Insert . : N ( O - Overwrite, I - Ins Mbr, OI - Both, N - None) Processing Mode. . : B ( F - Foreground, B - Batch) Batch JCL Status . : C ( C - New Dataset, A - Add to existing Dataset) Advanced Options . : N ( Y - Change Defaults, N - None) Preallocate file . : N ( Y - Prompt for allocation info, N -Use Defaults) File type : ( 1 - PDS, 2 - PS, 3 - VSAM, 4 - PDSE) Enter VIEW in the command field to VIEW an archive To EXIT Press PF3 Press ENTER to process For HELP Press PF1
Based upon the panel input, commands are built and included in the decompress job’s input (SYSIN) stream. The commands generated are explained in Chapter 7 of this manual. The individual panel fields and their effect on the processing are described in the following table.
Field Description
Archive Name Enter the name of the archive. It can be in the form of DATA.SET.NAME or DATA.SET.NAME(MBR). Standard data set naming conventions apply. Place the data set name in single quotes (‘…’) to prevent using the TSO prefix as the first qualifier. This option can be turned off using the Configuration option explained earlier.
File selection This field is used to specify what file(s) are to be extracted. A fully-qualified name can be entered or standard wildcards can be used to select multiple files. See Chapter 3 for rules on file selection.
Rename To This field is used to specify a different high level qualifier for the extracted data set(s). This allows the renaming of data set(s) as they are extracted. The input is used to build a UNZIPPED_DSN command. for the extracted data set(s). If &SYSUID is entered in this field, it will be replaced with the TSO user id.
File Decryption Enter a ‘Y’ or ‘N’. A ‘Y’ indicates that the file to be extracted is encrypted. A password will be requested. This field is initialized to ‘N’.
317
Field Description
More Files Enter a ‘Y’ or ‘N’. A ‘Y’ will display another panel where up to 10 additional file specifications can be entered. The same rules apply as stated in the ‘File Selection’ field above. This field is initialized to ‘N’.
Security required If decryption or authentication is required for this archive or the files within the archive select ‘Y”. Additional panels will guide you through the security requirements.
Simulation Mode Specifying a ‘Y’ in this field will run the extract in simulation mode. This is used to determine what the resulting names of the extracted data sets will be and where they will be stored without actually writing any files. The command built is SIMULATION(Y). This field is initialized ‘N’.
Integrity Check Specifying a ‘Y’ in this field will check the integrity of the files within the zip archive. No file(s) are actually extracted. This generates a TEST(Y) command. This field is initialized to a ‘N’.
Overwrite/Insert Specifying an ‘O’ in this field will overwrite a file that has the same name as an extracted data set. Specifying an ‘I’ will add the extracted data set to an existing PDS as a new member. An ‘OI’ or ‘IO’ in this field will build both commands. The commands built could be OVERWRITE(Y) and/or INSERT_MEMBER(Y).
Processing Mode Specifying a ‘F’ in this field will run the extract as a foreground task. Specifying a ‘B’ will build JCL for a batch job. The JCL will be displayed so it can reviewed and/or modified before submission. The job is submitted by the TSO SUBMIT command.
Advanced Options Specifying a ‘Y’ in this field will the display the current defaults for unzip processing and allow them to be changed and included as commands in this extract. This is the same process described for Option ‘UD’ earlier. As the options are changed, they are flagged with the string ‘**Adv Options**’. This field is initialized to a ‘N’.
Batch JCL Status Specifying a ‘C’ in this field will create a new job to be submitted in a batch run. Specifying a ‘A’ in this field will continue adding generated JCL to an already existing file to be submitted as multiple steps in one job. Using first a ‘C’ option on one panel then a series of other panls using the ‘A’ option you may generate a series of steps to process as one job. For example, you may want to build a ZIP archive and then View that archive. By using this feature you can generate the ZIP JCL from the Z Option and then go to the View panel and generate the View JCL where you will then submit the batch job.
Preallocate File Specifying a ‘Y’ in this field will allow allocation defaults for the extracted files to be overridden. An ‘N’ results in the defaults.
File Type If pre-allocation is selected (see above), then this field is used to specify what type of file is to be allocated. The user enters a 1 for a PDS, a 2 for a sequential file, a 3 for a VSAM file, or a 4 for a PDSE file. The appropriate panel where the allocation specifications can be entered is displayed based on this input. If this field is left blank, the file type is determined by the attributes of the archived file.
After all the fields have been entered, press “Enter” to process the panel and build the extract job. To display the UNZIP help information, press PF1. Enter ‘VIEW’ as a primary command to view the current contents of the specified zip archive file. The VIEW option is explained below under Option ‘V’.
+-----------------------------------------------------------------------------+ | SecureZIP UNZIP Processing | | Command ===> | | | | Security options: | | Encrypt Facilities : IBMHARDWARE,IBMSOFTWARE,SECUREZIP / for list | | Hashing Facilities : IBMHARDWARE,SECUREZIP / for list | | |
318
| Password access : N ( Y Password prompt) Display Typed Password: N | | ------------------------------------------------------------------------- | | SecureZIP certificate-based operations. | | | | Recipients : N ( Y - Digital Certificate Decryption) | | | | Authentication: | | Archive : N ( Y - Authenticate Archive Directory signature) | | Files : N ( Y - Authenticate File signatures) | | Validation Policy: Y Trusted Y Expired Y Revoked Y Tampercheck | | | | ------------------------------------------------------------------------- | | Reporting: | | Certificate Report : Y ( Y - Recipients show in SYSPRINT) | | | +-----------------------------------------------------------------------------+
Using Security The panel shown above is used to specify options for the password protection, recipient based decryption, and authentication of the files and archive.
Enter ‘Y’ to select an option.
+---------------------------------------------------------------------------+ | SecureZIP Encrypted File Password | | Command ==> | | | | File is encrypted. Enter password. | | | | Data Set Name: | | | | | | Password (up to 250 characters): | | ....5...10....5...20....5...30....5...40....5...50....5...60....5...70 | | | | | | | | Re-enter password: | | | | | | | | | | Press ENTER to continue, PF3 to terminate processing. | | | | | | |
Select Password Protect The panel shown above is used to specify the password used to decrypt the file(s).
+-----------------------------------------------------------------------------+ | SecureZIP Encryption | | OPTION ===> | | More: | | | | Recipients | | | | / to Edit the profile used to satisfy DB: and LDAP: requests. |
319
| DB Profile > 'PKWARE.MVS.PROFILES(DBPROF)' | | LDAP Profile> 'PKWARE.MVS.PROFILES(LDAPPROF)' | | | | / Edit a file containing a set of -RECIPIENT commands. | | S Search the Local Certificate Store to build a list | | M Data set member selection list | | Recipient List: 'PKWARE.MVS.PROFILES($RECIPX)' | | | | Individual Recipients: A -RECIPIENT() request will be built for each of | | of the following requests. | | 1. | | 2. | | 3. | | 4. | | 5. | | | +-----------------------------------------------------------------------------+
Select Recipients The panel shown above is used to specify the recipient certificates used to decrypt the files in the archive.
+-----------------------------------------------------------------------------+ | SecureZIP Archive Authentication | | Command ===> | | Archive File Information: | | Archive Name : 'FPD.MVS.SPKZLIBS.DEC31.ZIP' | | Specific signers : N ( Y - Verify against a list of signatories) | | ( N - A generic -AUTHCHK(ARCHIVE)) | | | | / Local Store Data Base Profile | | DB Profile > 'PKWARE.MVS.PROFILES(DBPROF)' | | List the signing certificates to be used if Specific signers=Y above. | | / Edit a file containing a set of -AUTHCHK commands. | | S Search the Local Certificate Store to build a list | | M Data set member selection list | | Archive Signers List: 'PKWARE.MVS.PROFILES($AUTHARC)' | | | | Individual Signers: An -AUTHCHK() request will be built | | for each of the following requests. | | 1. DB:CN=PKWARE TEST1,PASSWORD=Frank | | 2. | | 3. | | 4. | | 5. | | | +-----------------------------------------------------------------------------+
Archive Authentication The panel shown above is used to specify the certificates used to authenticate the archive.
+-----------------------------------------------------------------------------+ | SecureZIP File Authentication | | Command ===> | | Archive File Information: | | File Name : FPD.TEST.ZIP | | Specific signers : N ( Y - Verify against a list of signatories) | | ( N - A -AUTHCHK(FILES) generated) |
320
| | | / Local Store Data Base Profile | | DB Profile > 'PKWARE.MVS.PROFILES(DBPROF)' | | List the signing certificates to be used if Specific signers=Y above. | | / Edit a file containing a set of -AUTHCHK commands. | | S Search the Local Certificate Store to build a list | | M Data set member selection list | | File Signers List: | | | | Individual Signers: An -AUTHCHK() request will be built | | for each of the following requests. | | 1. | | 2. | | 3. | | 4. | | 5. | | |
File Authentication The panel shown above is used to specify the certificates used to authenticate the file(s).
SYSPRINT Browse (Option ‘S’)
This option displays the output of the last on-line operation. It is displayed in a standard ISPF browse panel. If the return code of an on-line operation exceeds the lowest allowable return code (see Configuration), then the output is automatically displayed. This option allows the browsing of the output from a run with any return code. An example of this display is shown below.
Menu Utilities Compilers Help BROWSE FPD.SECZIP9.SYSOUT Line 00000000 Col 001 132 Command ===> Scroll ===> PAGE ****************************** Top of Data************************************** ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright. 1989-2006 PKWARE Inc. All Rights Reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=7060 Processor Group=00 Serial Number=00052 ZPLI001I OS Level: HBB7707 SP7.0.6 **************************************** * Commands generated from panel input. * **************************************** -SUPPRESS_DYNALLOC_MSGS -TRACE_DYNALLOC(0) -ARCHIVE_DSN(PKWARE.MVS.ZIP) -ACTION(EXTRACT) -OUTFILE_DSNTYPE(SEQ) -OUTFILE_OVERWRITE(Y) -UNZIPPED_DSN(**,FPD.T074526.PKZIP51.TEMP) FPD/TEST/SEQ1 -CALLMODE(ISPF) -TRACEDALC0 -TRACE_DYNALLOC(0) ZPAM030I INPUT Archive opened: PKWARE.MVS.ZIP ZPEX002I FPD/TEST/SEQ1
321
Messages (Option ‘M’)
This option allows you to browse the HELP data set containing the PKZIPz messages. Each message is a separate member. Select option ‘M’, do a (L)ocate on the message id, and then select that member. The text of the message, any system and/or user response, and the invoking module are displayed. An example of the display for the message list is shown below.
Menu Functions Utilities Help ______________________________________________________________________________ BROWSE PKWARE.MVS.HELP Row 00001 of 00290 Command ===> Scroll ===> CSR Name Prompt Size Created Changed ID _________ $CONTACT 112 2002/07/23 2005/09/28 16:11:47 R900PR _________ $DBXRSNC 35 2005/02/15 2005/02/15 17:19:23 R900PR _________ $DEFAULT 29 2002/11/26 2002/11/26 09:18:25 R900PR _________ $ENCRYPT 168 2004/06/10 2005/10/17 08:42:45 R900PR _________ $MESSAGE 50 2002/09/12 2005/02/15 14:52:15 R900PR _________ $SCANCRT 165 2005/10/04 2005/10/21 11:12:26 R900PR _________ $WHATNEW 396 2006/03/16 2006/03/16 05:52:45 R900PR _________ API1R000 11 2003/11/19 2003/11/19 10:49:08 R900PR _________ API1R004 16 2003/11/19 2003/11/19 13:25:18 R900PR _________ API1R008 16 2003/11/19 2003/11/19 13:30:11 R900PR _________ API1R012 18 2003/11/19 2003/11/19 13:36:16 R900PR _________ API1R016 16 2003/11/19 2003/11/19 13:48:17 R900PR _________ API1R020 16 2003/11/19 2003/11/19 13:51:50 R900PR _________ API1R024 16 2003/11/19 2003/11/19 13:53:59 R900PR _________ API1R028 15 2003/11/19 2003/11/19 13:56:46 R900PR _________ API1R032 16 2003/11/19 2003/11/19 14:00:26 R900PR _________ API1R040 18 2003/11/19 2003/11/19 14:03:12 R900PR _________ API1R096 20 2003/11/19 2003/11/19 13:19:05 R900PR _________ CRYPTOSR 155 2006/03/14 2006/03/14 14:25:22 R900PR
If you wish to see the message text for message ZPAM914E, enter a L ZPAM9, select ZPAM914E, and press “Enter”. The text for the message is displayed in an ISPF browse panel as shown below.
Menu Utilities Compilers Help sssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss BROWSE PKWARE.MVS.HELP(ZPAM914E) - 01.00 Line 00000000 Col 001 080 Command ===> Scroll ===> CSR ********************************* Top of Data ********************************** ******************************************************************************** * * * ZPAM914E An error occurred attempting to locate a Local Directory entry. * * * * Explanation: The Archive Manager was reading through the input Archive * * by using offsets and lengths according to other directory * * entries. A Local Directory Header was expected at a * * specific offset in the file, but the eye-catcher was not * * present there. * * * * Note: The Local Directory begins with X'504B0304' * * * * System Response: Processing is terminated. * * * * User Response: Determine whether the file has been truncated. * * * * Invoking module: <ACAMGR> * * * ********************************************************************************
322
License Display (Option ‘L’)
This option displays information about the PKZIPz license in effect on this processor. The initial information produced in the list is your customer number and customer name along with the current processor serial number. Selecting this option displays the license data set using the high-level qualifier you specified in your ACZDFLTS and appending LICENSE. Using that data set the license data is reported and displayed.
An example of the display generated by this option is shown below.
BROWSE FPD.PKLIC.TEMP Command ===> *********************************************************** Top of Data ZPLI200I A LICENSE REPORT HAS BEEN REQUESTED ON 02/14/06 AT 4:05pm VER: 9.0 IN PKWARE.MVS900.LICENSE ZPLI200I For Technical Support assistance, please contact Product Services Division ZPLI200I at 937-847-2687 or go on-line at http://www.pkware.com/business_and_developers/support ZPLI200I Portions copyright (C) 1989-2006 PKWARE, Inc. All rights reserved. ZPLI200I Reg. U.S. Pat. and Tm. Off. Patent No. 5,051,745 ZPLI200I Other U.S. and international patent applications pending. ZPLI200I Portions of this software include RSA BSAFE(R) cryptographic ZPLI200I or security protocol software from RSA Security Inc. ********************************************************************************* ZPLI200I SecureZIP IS LICENSED TO CUSTOMER # 000012805 ZPLI200I - CUSTOMER NAME - PKWARE, INC. ZPLI200I CPU model 2066 with 1 online ZPLI200I Service units per second per online CPU is 5612.07 ZPLI200I Approximate total MIPS (SUs/SEC / 48.5 * #CPUs) is 115.71 ZPLI200I Central Processing Complex (CPC) Node Descriptor: CPC ND = 002066.0B1.IBM.02.00000001263B ZPLI200I CPC ID = 00 Type(002066) Model(0B1) Manufacturer(IBM) Plant(02) Seq Num(00000001263B) ZPLI200I CPU serial number for CPU 1 is 04263B2066 (4263B), version code 00, model 0B1. ZPLI200I Model from CPC SI ********************************************************************************* ZPLI200I COMPRESSION IS LICENSED ON THE FOLLOWING PROCESSORS ZPLI200I SERIAL# *0263B PROCESSOR TYPE 2066 VERSION/MODEL 0B1 WITH AN EXPIRATION DATE OF 02/28/2400 ZPLI200I DECOMPRESSION IS LICENSED ON THE FOLLOWING PROCESSORS ZPLI200I SERIAL# *0263B PROCESSOR TYPE 2066 VERSION/MODEL 0B1 WITH AN EXPIRATION DATE OF 02/28/2400 ZPLI200I GZIP SUPPORTED FILES LICENSED ON THE FOLLOWING PROCESSORS ZPLI200I SERIAL# *0263B PROCESSOR TYPE 2066 VERSION/MODEL 0B1 WITH AN EXPIRATION DATE OF 02/28/2400 ZPLI200I ISPF IS LICENSED ON THE FOLLOWING PROCESSORS ZPLI200I SERIAL# *0263B PROCESSOR TYPE 2066 VERSION/MODEL 0B1 WITH AN EXPIRATION DATE OF 02/28/2400 ZPLI200I COMMAND LINE INTERFACE IS LICENSED ON THE FOLLOWING PROCESSORS ZPLI200I SERIAL# *0263B PROCESSOR TYPE 2066 VERSION/MODEL 0B1 WITH AN EXPIRATION DATE OF 02/28/2400 ZPLI200I ADVANCED ENCRYPTION IS LICENSED ON THE FOLLOWING PROCESSORS ZPLI200I SERIAL# *0263B PROCESSOR TYPE 2066 VERSION/MODEL 0B1 WITH AN EXPIRATION DATE OF 02/28/2400 ZPLI200I DIRECTORY INTEGRATION IS LICENSED ON THE FOLLOWING PROCESSORS ZPLI200I SERIAL# *0263B PROCESSOR TYPE 2066 VERSION/MODEL 0B1 WITH AN EXPIRATION DATE OF 02/28/2400 ZPLI200I ZIP64 LARGE FILE SUPPORT IS LICENSED ON THE FOLLOWING PROCESSORS ZPLI200I SERIAL# *0263B PROCESSOR TYPE 2066 VERSION/MODEL 0B1 WITH AN EXPIRATION DATE OF 02/28/2400 ZPLI200I SELF EXTRACTION CREATOR IS LICENSED ON THE FOLLOWING PROCESSORS ZPLI200I SERIAL# *0263B PROCESSOR TYPE 2066 VERSION/MODEL 0B1 WITH AN EXPIRATION DATE OF 02/28/2400 *********************************************************************************
323
Certificate Stores (Option ‘CS’)
For system administrators to access the Certificate Store Administration and Configuration, enter “CS” in the Option field from the main SecureZIP panel.
SecureZIP Certificate Store Administration Option ===> Select one of the following options and press Enter: 1 Local Certificate Store Administration 2 LDAP Certificate Store Configuration 3 x.509 Certificate Utilites
What’s New (Option ‘W’)
This option displays information about the changes included in this release of PKZIPz.
Contact PKWARE (Option ‘A’)
This option displays information on how to contact PKWARE. Additionally, the display contains information on the data to provide to PKWARE when reporting problems about PKZIPz.
324
14 User API Processing
Overview
A User Application Program Interface (API) allows the user to programmatically shape certain functions of the PKZIP/PKUNZIP process. Processing interface points currently defined are:
The format and content of data records to be archived
The target data set names of files to be extracted.
These User API functions are distinct from, but are not incompatible with, an application program calling PKZIP or PKUNZIP as a utility. See Chapter 15.
Data Record Transformation API for ZIP processing. The User API provides a means to restructure a data record before compression takes place. A common use is to transform binary and packed decimal fields into display-format numerics. This is useful when the system intended to receive the ZIP archive does not easily handle these field formats.
File Name Manipulation API for UNZIP processing. The User API provides a means to transform filenames into manageable IBM MVS-compatible data set names. This is useful when specialized re-direction of files is required that exceeds the capabilities of the PKZIPz command set.
Invocation
You may have one User API for file name processing and one User API for data record transformation processing. To use the APIs, certain information must be provided to PKZIPz. The User APIs are invoked by the use of control cards. Each control card is specific to the type of API being invoked. There are FILENAME control cards and DATA_TRANS control cards. The APIs to be invoked must be placed in a load library accessible to PKZIPz through a concatenated STEPLIB, JOBLIB or the system linklist.
325
During initialization, PKZIP initializes the interfaces required for API processing based on the information in the control cards. If there is a FILENAME API, for example, this API is loaded and made available for processing. When PKZIP enters the appropriate routine, it calls the API with a list of data addresses contained in DCTMAPIU (Assembler) or COBMAPIU (COBOL), the main control block passed to the API. DCTMAPIU and COBMAPIU are in INSTLIB. The API routine then gets control, manipulates the data appropriately, and returns control to PKZIP for completion of that call. The formats for both file level and data level calls to the API follow a similar protocol.
Informational and error messages are placed in the print output for reference. For archival processing, an extended attribute is placed in the archive to identify this as a file that has been affected by a User API.
The APIs must be reentrant and follow standard linkage conventions. See the example User APIs.
The API facility allows the user to determine the name of the API module, the processing to occur when there is an error, the amount of workspace the User API routine requires, a passed parameter to the API, and the amount of tracing information for debugging purposes.
By default, the system does not invoke a User API.
Negation of API processing Use of the NOAPI control card negates the initialization and possible use of all User API processing. This is important for language environment operations that do not support CEEPIPI being in operation (such as C++ calling SecureZIP).
This command must be passed in the execute parameters (not in the defaults module or a command stream) so that it takes effect early in the SecureZIP initialization process.
When NOAPI is in use, the DATA_TRANS and FILENAME APIs are not available.
Execution Environment The environment established for the User API is determined by the language specified on the control cards. If COBOL is specified, a language environment is established through the use of preinitialization services using the IBM LE-supplied routine CEEPIPI that is available on your system. This allows the API to utilize the HLL environment when it is written in COBOL.
If the API is written in assembler, then a non-LE load and branch is use to pass control to the API, and a HLL environment is not established. See the example User APIs to better understand the passing of parameters between both types.
Since there are two API languages that can be used, it is very important to identify the correct language on the control card. Unpredictable results will occur if the language identified on the control card is not the language that was used to code the User API.
Run-time options used for the LE environment are the runtime options established for your site by the systems programmer or, if no changes have been made, the IBM defaults.
POSIX(ON) is not supported as a run-time option for User APIs.
326
File Name Manipulation API File name manipulation takes place in the UNZIP process. Certain platforms allow file name structures that are incompatible with the standard IBM MVS format. The File Name API is presented with the EBCDIC representation of the archive file name, a copy of the candidate MVS data set name created according to the PKUNZIP commands, and some control information. If the output file is a PDS or PDSE, the new file name must conform to PDS file name rules, which includes a valid data set name and member name enclosed in parentheses. The API cannot change the output data set organization. The file type attributes are provided, identifying the file as VSAM, PDS or SEQUENTIAL. If a sequential data set was being created and the input area contained the value “TEST/INPUT/FILE”, the output candidate data set name would be “TEST.INPUT.FILE”.
The User API routine has the option of either keeping the candidate data set name or manipulating the data set name further. PKZIP will attempt to use whatever name is presented back in the output area. Unpredictable results may occur if the data set name does not conform to MVS requirements for the data set type involved.
PDS files: If the input file is zipped from a PDS and contains the PDS extended attributes, an input area of “TEST/PDS/MEMBERA” has an output candidate containing “TEST.PDS(MEMBERA). The user can work with the output area or re-parse the input file name, moving it to the output area. The output area of an archive created on a non-mainframe platform may have a name that is not in a standard IBM MVS format and is likely to produce unpredictable results.
VSAM files: The API is entered up to 3 times depending on the type of VSAM file. The first time for the base cluster, and the following times for the data and index components respectively, the API control block indicates the data and index component calls. The data and index API call’s input area is not the raw input the cluster call received; rather, it contains whatever changes have been made to the file on the cluster call. The input file name for the data and index calls are the result of changes made to the cluster file name.
Data Record Transformation API Data RECORD TRANSFORMATION takes place during ZIP processing. The User API routine is presented with the raw file data immediately after the record is read. The API can filter out records, expand or reduce a record’s size, unpack fields, and convert binary data to display-numerics (also referred to as field-level manipulation). This is useful when sending ZIP archives to target systems which cannot readily handle these formats. Manipulation can be performed on the record based on control cards and other sources.
The User API routine is passed control information such as input file data set organization, file name, record length, and the translation mode (text or binary) that is being performed.
PKZIP command-controlled features are still operative when the User API routine is operative.
If requested, DATA_TYPE(DETECT) takes place before the first record is presented to the User API routine. EBCDIC to ASCII translation and DATA_DELIMITER functions are performed according to PKZIP command settings after the User API routine has completed its work on each record.
A first-call indicator is set on to notify the API that this is the first call to the API for the selected file, during which the API can perform certain first-time functions to improve efficiency. The working storage provided is persistent for the entire run. The return code
327
(register 15) from the API is checked. If it is zero, the record is processed; if it is 4, the record is rejected.
User API Samples
Below are examples of how to invoke the User APIs and sample output listings. Members in INSTLIB contain sample JCL for invoking the User APIs along with sample assembler and COBOL programs that you may use as a reference for coding your User APIs.
JCL and Sample Programs
Assembler ASMDAPIJ contains the JCL to invoke the sample Data Record Transformation API.
//ASMDAPI JOB (ACCT),'NAME',MSGCLASS=H, // CLASS=A,REGION=4M,NOTIFY=&SYSUID //* //* THIS SAMPLE WILL CALL THE DATA TRANSACTION API, CONVERTING PACKED //* FIELDS TO DISPLAY AND ',' DELIMITING EACH FIELD. //* //ZIP EXEC PGM=PKZIP //SYSPRINT DD SYSOUT=* //SYSIN DD * -TEXT -VERBOSE PKWARE.MVS.INSTLIB(SAMPDAPI) -ARCHIVE(PKZIP.DATAAPI.ZIP) -DATA_TRANS_API_PARM(TEST PASS DATA TO API) -DATA_TRANS_API_NAME(ASMDTAPI) -DATA_TRANS_API_LANGUAGE(ASM) -DATA_TRANS_API_WORKSIZE(4096) -DATA_TRANS_API_TRACE(0) -TRACE_API(0) //
Assembler Source ASMDTAPI contains the sample assembler program.
********************************************************************* * AUTHOR: PKWARE INC. * * NAME: ASMDTAPI * * ENVIRONMENT: S390 * * PURPOSE: SAMPLE API TO CONVERT DATA RECORD TO BE COMMA * * DELIMITED BY FIELD FOR PC SPREAD SHEET. THE * * RECORD WILL CONTAIN PACKED DATA WHICH WILL NEED * * TO BE UNPACKED FOR THE PC PLATFORM. * * * * HISTORY: BASE V1R0M0 03/30/2003 * * * * MAINTENANCE LOG BEGIN * ********************************************************************* * CALL LINKAGE: STANDARD. * * PARAMETER LIST: *
328
* API CONTROL BLOCK * ********************************************************************* ASMDTAPI CSECT STM R14,R12,12(R13) SAVE REGISTERS LR R12,R15 PRIME BASE REG USING ASMDTAPI,R12 ………………… ………………..
Assembler JCL ASMFAPIJ contains the JCL to invoke the sample Filename API.
//ASMFAPI JOB (ACCT),'NAME',MSGCLASS=H, // CLASS=A,REGION=4M,NOTIFY=&SYSUID //* //* THIS EXAMPLE WILL CONVERT THE FILE NAME ON EXTRACTION //* //UNZIP EXEC PGM=PKUNZIP //SYSPRINT DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKZIP.SAMPLE.ZIP) -VERBOSE -EXTRACT -FILENAME_API_NAME(ASMFNAPI) -FILENAME_API_LANGUAGE(ASM) -FILENAME_API_WORKSIZE(4096) -FILENAME_API_ERROR(ABEND) -FILENAME_API_PARM(SAMPLE FILENAME API) -FILENAME_API_TRACE(0) -TRACE_API(0)
Assembler Source ASMFNAPI contains the sample assembler program.
********************************************************************* * AUTHOR: PKWARE INC. * * NAME: ASMFNAPI * * ENVIRONMENT: S390 * * PURPOSE: SAMPLE API TO MODIFY FILE NAMES ON EXTRACTION * * EXAMPLE: * * SEQUENTIAL * * I/P FILE: SAMPLE/TEST/FILE * * O/P FILE: PKZIP.APIFNSEQ.FILE * * * * PDS * * I/P FILE: SAMPLE/LIST/FILEA * * O/P FILE: PKZIP.APIFNPDS(FILEA) * * * * VSAM * * I/P FILE: INPUT/KSDS/FILE * * O/P FILE: PKZIP.APIFNVSM.FILE * * PKZIP.APIFNVSM.FILE.DATA * * PKZIP.APIFNVSM.FILE.INDEX * * * * HISTORY: BASE V1R0M0 03/30/2003 * …………….. …………………. …………………..
329
DCTMAPIU DSECT DCTMAPIU is the DSECT that describes the parameters passed to the User API
DCTMAPIU DSECT MB041803 * *** * PARAMETERS PASSED TO THE USER EXIT *** * APIP_START DS 0F APIP_FILENAME_SOURCE_LGTH DS F LENGTH OF SOURCE APIP_FILENAME_SOURCE@ DS A(0) SOURCE LOCATION OF DATA APIP_FILENAME_TARGET_LGTH DS F LENGTH OF TARGET APIP_FILENAME_TARGET@ DS A(0) TARGET ADDRESS OF MOD SOURCE DATA APIP_RESET ORG APIP_START APIP_DATA_TRANS_SOURCE_LGTH DS F LENGTH OF SOURCE APIP_DATA_TRANS_SOURCE@ DS A(0) SOURCE LOCATION OF DATA APIP_DATA_TRANS_TARGET_LGTH DS F LENGTH OF TARGET APIP_DATA_TRANS_TARGET@ DS A(0) TARGET ADDRESS OF MOD SOURCE DATA APIP_WA_LGTH DS F GETMAINED WA LENGTH FOR EXIT APIP_WORK@ DS F GETMAINED WORK AREA FOR EXIT APIP_USER_SW DS F ORG APIP_USER_SW ……………. …………….. …………………
COBOL
COBOL JCL COBDAPIJ contains the JCL to invoke the sample Data Record Transformation API.
//COBDAPI JOB (ACCT),'NAME',MSGCLASS=H, // CLASS=A,REGION=4M,NOTIFY=&SYSUID //* //* THIS SAMPLE WILL CALL THE DATA TRANSACTION API, CONVERTING PACKED //* FIELDS TO DISPLAY AND ',' DELIMITING EACH FIELD. //* //ZIP EXEC PGM=PKZIP //SYSPRINT DD SYSOUT=* //SYSIN DD * -TEXT -VERBOSE PKWARE.MVS.INSTLIB(SAMPDAPI) -ARCHIVE(PKZIP.DATAAPI.ZIP) -DATA_TRANS_API_PARM(TEST PASS DATA TO API) -DATA_TRANS_API_NAME(COBDTAPI) -DATA_TRANS_API_LANGUAGE(COBOL) -DATA_TRANS_API_WORKSIZE(4096) -DATA_TRANS_API_TRACE(0) -TRACE_API(0) //
COBFAPIJ contains the JCL to invoke the sample Filename API.
330
//COBFAPI JOB (ACCT),'NAME',MSGCLASS=H, // CLASS=A,REGION=4M,NOTIFY=&SYSUID //* //* THIS EXAMPLE WILL CONVERT THE FILE NAME ON EXTRACTION //* //UNZIP EXEC PGM=PKUNZIP //SYSPRINT DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKZIP.SAMPLE.ZIP) -VERBOSE -EXTRACT -FILENAME_API_NAME(COBFNAPI) -FILENAME_API_LANGUAGE(COBOL) -FILENAME_API_WORKSIZE(4096) -FILENAME_API_ERROR(ABEND) -FILENAME_API_PARM(SAMPLE FILENAME API) -FILENAME_API_TRACE(0) -TRACE_API(0)
COBMAPIU copy member COBMAPIU is the COBOL copy member that describes the parameters passed to the User API
01 COBMAPIU. *** * PARAMETERS PASSED TO THE USER API *** 02 APIP-COMMON. 03 APIP-SOURCE-LGTH PIC 9(8) BINARY. 03 APIP-SOURCEP POINTER. 03 APIP-TARGET-LGTH PIC 9(8) BINARY. 03 APIP-TARGETP POINTER. 03 APIP-WA-LGTH PIC 9(8) BINARY. 03 APIP-WORKP PIC 9(8) BINARY. 03 PIC X(2). 03 APIP-FILENAME-SW PIC X. 88 APIP-FILENAME-ZIP VALUE X'80'. 88 APIP-FILENAME-UNZIP VALUE X'40'. 03 APIP-DATA-TRANS-SW PIC X. 88 APIP-DATA-TRANS-ZIP VALUE X'80'. 88 APIP-DATA-TRANS-UNZIP VALUE X'40'. 03 APIP-FILETYPE PIC XX. 88 APIP-VSAM-BASE VALUE 'VS'.
Sample input file - SAMPDAPI SAMPDAPI is the input file to the Data Record Transformation API. Use with ASMDAPIJ or COBDAPIJ
-CAUTION- Profile changed to CAPS OFF (from CAPS ON) because data contains lower case characters. -CAUTION- Data contains invalid (non-display) characters. Use command ===> FIND P'.' to position cursor to these DAVID JONES 11 FIRST ST ANYWHERE OH45999032665 ϱ042102 KAREN FRANKLIN 456 MAIN ST ANYWHERE OH45999071162 ¬ ç¤090803 MARY HOOVER 1600 PENN LN ANYWHERE OH45999030771 " À 041703 JANICE PATTEN 22 SECOND ST ANYWHERE OH45999042760 ç 062303 JANICE PATTEN 44 FOURTH ST ANYWHERE OH45999082766 /"030403 JOYCE JONES 22 SECOND ST ANYWHERE OH45999122563 ß? Ѭ020502 KAREN FRANKLIN 55 FIFTH ST ANYWHERE OH45999042162 ° â¤042402
331
GREGG MADISON 123 SESAME ST ANYWHERE OH45999031880 á" â?080102 WALTER MADISON 44 FOURTH ST ANYWHERE OH45999032053 ñ l¬040802 JOHN DOE 456 MAIN ST ANYWHERE OH45999011356 l? 071202 PETER MADISON 123 SESAME ST ANYWHERE OH45999081765 &"030202 JANE SMITH 1010 WINS RD ANYWHERE OH45999021368 à è¤030102 JANICE WALTERS 22 SECOND ST ANYWHERE OH45999032557 DZ 052803 JANE MADISON 123 SESAME ST ANYWHERE OH45999070752 î DZ061402 ……………….. ………………….. ……………………..
Output from sample jobs
ASMFNAPI Sample Output This is an example of a Filename API, ASMFNAPI, which takes the first two nodes of the archived file and changes them to PKZIP.APIFNSEQ. The message ZPAP010I is presented once per run to document that an API has been invoked.
ZPGE001T UNZIP STARTUP STORAGE QUERY: 24BIT= 6100K 31BIT= 32768K ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright 1989-2006 PKWARE Inc. All rights reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=2066 Processor Group=00 Serial Number= ZPLI001I OS Level: HBB7707 SP7.0.4 * EXTRACT AND CHANGE NAME -ARCHIVE_DSN(FPD.APIIT.ZIP) -FILENAME_API_NAME(ASMFNAPI) -FILENAME_API_LANGUAGE(ASM) -FILENAME_API_ERROR(IGNORE) FPD/TEST/SEQ1 ZPAP010I Filename Module ASMFNAPI Loaded ZPAM030I INPUT Archive opened: FPD.APIIT.ZIP ZPEX002I FPD/TEST/SEQ1 ZPEX003I Extracted to PKZIP.APIFNSEQ.SEQ1 ZPAM140I FILES: EXTRACTED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
XSMFNAPI Sample Output
FILENAME_API_ERROR Using STOPRUN Option This is an example of a Filename API, XSMFNAPI, which was not found. The FILENAME_API_ERROR(STOPRUN) option was selected. The API could not find and load the API (see the message ZPAP005E below) and, because of the STOPRUN (or if ABEND is specified) option, PKZIP ends without processing any data.
ZPGE001T UNZIP STARTUP STORAGE QUERY: 24BIT= 6100K 31BIT= 32768K CACHE= ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright 1989-2006 PKWARE Inc. All rights reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=2066 Processor Group=00 Serial Number= ZPLI001I OS Level: HBB7707 SP7.0.4
332
* EXTRACT AND CHANGE NAME -ARCHIVE_DSN(FPD.APIIT.ZIP) -FILENAME_API_NAME(XSMFNAPI) -FILENAME_API_LANGUAGE(ASM) -FILENAME_API_ERROR(STOPRUN) -OUTFILE_OVERWRITE(Y) FPD/TEST/SEQ1 ZPAP005E Filename Module XSMFNAPI Failed to Load ZPTM002I SUBTASK ( 2) EP: ACCMGR Ended - TCB: 008CF908 Comp: 00000008 ZPAM140I FILES: EXTRACTED EXCLUDED BYPASSED IN ERROR ZPAM140I 0 0 0 0 ZPMT002I PKZIP processing complete. RC=0000000C 12(Dec)
FILENAME_API_ERROR using IGNORE Option This is an example of a Filename API, XSMFNAPI, which was not found. The FILENAME_API_ERROR(IGNORE) option was selected. The API could not find and load the API (see the message ZPAP005E below) and, because of the IGNORE option, PKZIP continues processing as if there was no API specified.
ZPGE001T UNZIP STARTUP STORAGE QUERY: 24BIT= 6100K 31BIT= 32768K CACHE= ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright 1989-2006 PKWARE Inc. All rights reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=2066 Processor Group=00 Serial Number= ZPLI001I OS Level: HBB7707 SP7.0.4 * EXTRACT AND CHANGE NAME -ARCHIVE_DSN(FPD.APIIT.ZIP) -FILENAME_API_NAME(XSMFNAPI) -FILENAME_API_LANGUAGE(ASM) -FILENAME_API_ERROR(IGNORE) -OUTFILE_OVERWRITE(Y) FPD/TEST/SEQ1 ZPAP005E Filename Module XSMFNAPI Failed to Load ZPAM030I INPUT Archive opened: FPD.APIIT.ZIP ZPEX002I FPD/TEST/SEQ1 ZPEX003I Extracted to FPD.TEST.SEQ1 ZPAM140I FILES: EXTRACTED EXCLUDED BYPASSED IN ERROR ZPAM140I 1 0 0 0 ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
User API_Module Program Exception Trap This is an example of a user API, called FNEXIT, being invoked which subsequently abends with a PROGRAM EXCEPTION (S0C1). Using the default processing, PKZIPz traps the abend and prints the registers of the API at abend.
1ZPGE001T UNZIP STARTUP STORAGE QUERY: 24BIT= 6100K 31BIT= 32768K ZPLI001I SecureZIP(R) for z/OS, Version 9.0 - 06/26/2006 07.22 LVL(0) ZPLI001I Copyright 1989-2006 PKWARE Inc. All rights reserved. ZPLI001I SecureZIP (R) is a trademark of PKWARE, Inc. ZPLI001I Registered, Processor Type=2066 Processor Group=00 Serial Number= ZPLI001I OS Level: HBB7707 SP7.0.4 -ARCHIVE_DSN(FPD.APIIT.ZIP) -FILENAME_API_NAME(FNEXIT) -FILENAME_API_LANGUAGE(ASM) -FILENAME_API_WORKSIZE(1024) FPD/TEST/SEQ1 ZPAP010I Filename Module FNEXIT Loaded ZPAM030I INPUT Archive opened: FPD.APIIT.ZIP
333
ZPAP050E Filename Module FNEXIT ABEND at Address=80052B70 Cond Code=01 ZPAP090E Registers at entry to Abend ZPAP091E 00 - 03 00000950 008BF6B0 1757E790 5880B004 ZPAP091E 04 - 07 1757E7A0 8006536A 00011010 1757BCD8 ZPAP091E 08 - 11 00066FE0 00068000 8000F000 1757E7A0 ZPAP091E 12 - 15 00052B00 1758E858 8006537C 00000000 ZPEX072W OUTFILE_OVERWRITE(N) excluded overwrite of {FPD.TEST.SEQ1 ZPAM140I FILES: EXTRACTED EXCLUDED BYPASSED IN ERROR ZPAM140I 0 0 1 0 ZPMT002I PKZIP processing complete. RC=00000008 8(Dec)
334
15 Invoking PKZIP/PKUNZIP from an Application Program
PKZIP and PKUNZIP can be called (invoked dynamically) from other programs using standard calling conventions. Because PKZIP/PKUNZIP adheres to IBM’s standard linkage conventions, the passing of parameters is accomplished as described in the language reference manuals. Because standard conventions are used, the return code is passed back to your program.
PKZIPz is specifically designed to compress and decompress data sets. When designing and writing your program, the following items should be considered:
PKZIP/PKUNZIP adheres to standard IBM linkage conventions.
Return codes are passed back to your program via the standard conventions of the language used (for example, in Assembly language, return codes are passed back via register 15).
The configuration file will be used if available.
The parameters for PKZIP/PKUNZIP can be set by passing one or more parameters separated by a blank in the pass area supplied by the calling program. The length of the pass area is defined by the calling program. The length passed should reflect actual lengths of parameters passed to avoid excess parsing of unused storage (which may result in errors).
Specify the NOSYSIN command in the pass parameter area if you are not planning to use SYSIN for command input. Note that problems can occur if PKZIP attempts to open the SYSIN dataset after it has already been opened by the calling program.
When using call parameters for command input, the following commands (if used) should be contained within the first 256 bytes of the command stream and must be upper case: NOSYSIN, DM, ECHO, NOECHO, VERBOSE, QUIET.
It is your responsibility to allocate and free DD statements referenced in the run request (such as INFILE_DD).
Output is written to SYSPRINT.
To load PKZIP/PKUNZIP, the load library must in the link list, JOBLIB, or STEPLIB.
PKZIP and PKUNZIP are NOT Reentrant. However, they are serially reusable.
335
One way to use a program to call PKZIP is to set up a special setting in the parameters and to analyze return codes or to change the return. The included sample assembly program may be a good starting place to build such a pre-processor.
Sample source programs (and their JCL) are available in the data set pkware.mvspkware.mvs.INSTLIB. These samples demonstrate the dynamical calling of PKZIP by passing parameters and using SYSIN. The members in the following table are supplied in pkware.mvspkware.mvs.INSTLIB:
CALLASMJ JCL to compile, link and executes the Assembly sample CALLZIPA
CALLZIPA Sample Assembly source program to call PKZIP
CALLCOBJ JCL to compile, link and executes the COBOL sample CALLZIC
CALLZIPC Sample COBOL program source to call PKZIP
CALLPLIJ JCL to compile, link and executes the PL/I sample CALLZIPP
CALLZIPP Sample PL/I source program to call PKZIP
CALLREXJ JCL to run the REXX sample CALLZIPR
CALLZIPR Sample REXX source program to call PKZIP
CALLZCJ JCL to run the C sample CALLZC
CALLZC Sample C source program to call PKZIP
CALLZCPJ JCL to run the C++ sample CALLZCPP
CALLZCPP Sample C++ program source to call PKZIP
CALLZIPA Sample Assembly Source to Call PKZIP
CALLZIPA TITLE 'CALLZIPA - SecureZIP for z/OS PREPROCESSOR' *********************************************************************** * * * SecureZIP for z/OS (TM), DATA COMPRESSION, VERSION 9.0 * * COPYRIGHT. 1989-2006 PKWARE Inc. ALL RIGHTS RESERVED. * * * *********************************************************************** * * *NAME: CALLZIPA * *PURPOSE: Sample Assembly Program to fetch and call PKZIP * * Steps: - Pass Modified Parms * * - Examine The Return Code On Exit * * * * This sample Assembly programs demonstrates the ability to fetch * * and call PKZIP or PKUNZIP from an application program as a * * dynamic call (i.e., PKZIP and PKUNZIP are NOT linked into the * * program). There are three main variables used in calling PKZIP. * * First is the program variable (PKZIPEP) containing the name of * * program to call. The second variable is the parameters pass area * * which was passed from the JCL. You can build your own variable * * and use it as the PARMS to PKZIP by loading its address in EXECPARM.* * The third variable to be concerned about is the return code pass * * back from PKZIP/PKUNZIP program. This can be examine for other * * processing or verification. * * * * This Example is passing the parameter '- SHOW_SETTINGS'. If * * -NOSYSIN is also passed ('- SHOW_SETTINGS - NOSYSIN'), PKZIP would * * not read other parameters from SYSIN. This example will read *
336
* parameters from //SYSIN. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *********************************************************************** * REGISTERS EQUATES AND USAGE FOR PROGRAM CALLZIPA *********************************************************************** * ENTRY IN PROGRAM RETURN *R0 EQU 0 IRRELEVANT MACRO WORK RESTORED *R1 EQU 1 ADDR OF PARMS MACRO WORK RESTORED *R2 EQU 2 IRRELEVANT RESTORED *R3 EQU 3 IRRELEVANT COMMAND BUFFER MAPPING RESTORED *R4 EQU 4 IRRELEVANT RESTORED *R5 EQU 5 IRRELEVANT RESTORED *R6 EQU 6 IRRELEVANT RESTORED *R7 EQU 7 IRRELEVANT RESTORED *R8 EQU 8 IRRELEVANT RESTORED *R9 EQU 9 IRRELEVANT RESTORED *R10 EQU 10 IRRELEVANT RESTORED *R11 EQU 11 IRRELEVANT RESTORED *R12 EQU 12 IRRELEVANT *** BASE REGISTER *** RESTORED *R13 EQU 13 O/S SAVEAREA LOCAL SAVE/WORK AREAS RESTORED *R14 EQU 14 RETURN ADDR STANDARD RETURN ADDRESS RESTORED *R15 EQU 15 EP ADDR MACRO RET CODES RET CODE * *********************************************************************** * *** ESTABLISH STANDARD MODULE PROLOG. * *********************************************************************** * CALLZIPA CSECT CALLZIPA RMODE 24 CALLZIPA AMODE 31 * ** ESTABLISH BASIC LINKAGE * USING CALLZIPA,R15 TEMPORARY ADDRESSING SAVE (14,12) LA R14,SAVEAREA ST R14,8(R13) SAVE BACK OUR SAVE AREA ST R13,SAVEAREA+4 KEEP CALLER'S SAVE AREA LA R13,SAVEAREA LOCAL SAVE AREA ST R1,EXECPARM KEEP EXEC PARM ADDRESS LR R12,R15 ESTABLISH DROP R15 ADDRESSABILITY USING CALLZIPA,R12 USING R12 * ** LOAD THE PKZIP PROGRAM INTO STORAGE AND BRANCH-ENTER IT * L R3,=A(PKZIPEP) LOAD ADDRESS OF PROGRAM TO CALL * FETCH THE PROGRAM LOAD EPLOC=(R3) LR R15,R0 HAVE EP ADDRESS L R1,EXECPARM EXEC PGM=...,PARM='...' BASR R14,R15 * ** PLACE RETURN CODE EXAMINATION CODE BELOW * * C R15,=F'4' SAMPLE CHECK FOR RC4 * GOBACK L R13,SAVEAREA+4 GET CALLER'S SAVE AREA BACK RETURN (14,12),RC=(15) SAVEAREA DC 18F'0' EXECPARM DS F PASSED REG1 PKZIPEP DC CL8'PKZIP' LTORG ******** ***** ************************** ******************** R0 EQU 0
337
R1 EQU 1 R2 EQU 2 R3 EQU 3 R4 EQU 4 R5 EQU 5 R6 EQU 6 R7 EQU 7 R8 EQU 8 R9 EQU 9 R10 EQU 10 R11 EQU 11 R12 EQU 12 R13 EQU 13 R14 EQU 14 R15 EQU 15 END CALLZIPA.
CALLZIPC Sample COBOL Source to Call PKZIP
000100 ID DIVISION. 000200 PROGRAM-ID. CALLZIPC. 000300* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 000400* SecureZIP for z/OS (TM), DATA COMPRESSION, VERSION 9.0 * 000500* COPYRIGHT. 1989-2006 PKWARE Inc. ALL RIGHTS RESERVED. * 000600* * 000700* * 000800* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 000900 ENVIRONMENT DIVISION. 001000 INPUT-OUTPUT SECTION. 001100* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 001200* SecureZIP for z/OS (TM), DATA COMPRESSION, VERSION 9.0 * 001300* COPYRIGHT. 1989-2006 PKWARE Inc. ALL RIGHTS RESERVED. * 001400* * 001500* Program: CALLZIPC * 001600* * 001700* This sample COBOL programs demonstrates the ability to call * 001800* PKZIP or PKUNZIP from an application program as a dynamic * 001900* call (i.e., PKZIP and PKUNZIP are NOT linked into the * 002000* program). There are two main variables used in calling * 002100* PKZIP. First is the program variable which contains the * 002200* name of program to call. By making it a variable forces a * 002300* dynamic call to PKZIP. The second variable is the * 002400* parameters pass area in the LINKAGE SECTION. * 002500* The length is left up to the user, but the first two bytes * 002600* must be a binary length of the pass area. See CALL-PARMS * 002700* variables. * 002800* * 002900* This example is using the pass area of 100 bytes. This * 003000* Example is passing the parameter '- SHOW_SETTINGS'. If * 003100* -NOSYSIN also passed ('- SHOW_SETTINGS - NOSYSIN'), PKZIP * 003200* would not read other parameters from SYSIN. n This example * 003300* it will read parameters from //SYSIN. * 003400* * 003500* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 003600 FILE-CONTROL. 003700 DATA DIVISION. 003800 FILE SECTION. 003900 WORKING-STORAGE SECTION. 004000 01 CALL-PROGRAM PIC X(8). 004100 01 CALL-PARMS. 004200 02 CALL-PARM-LENGTH PIC 9(3) BINARY VALUE 100. 004300 02 CALL-PARM-DATA PIC X(100). 004400 LINKAGE SECTION.
338
004500 01 PARM-CARD. 004600 02 PARM-LENGTH PIC 9(4) BINARY. 004700 02 PARM-DATA PIC X(80). 004800 PROCEDURE DIVISION USING PARM-CARD. 004900 DISPLAY 'ABOUT TO CALL PKZIP'. 005000* Move Of Program Name To Variable Forces Dynamic Call. 005100 MOVE 'PKZIP' TO CALL-PROGRAM. 005200* 005300* Set the PARM Variable field used by PKZIP. 005400* If you do not want to read any parameters in PKZIP add -NOSYSIN 005500* 005600 MOVE '-SHOW_SETTINGS' TO CALL-PARM-DATA. 005700 CALL CALL-PROGRAM USING CALL-PARMS. 005800 DISPLAY 'PKZIP COMPLETE RC=' RETURN-CODE. 005900 STOP RUN..
CALLZIPP Sample PL/I Source to Call PKZIP
CALLZIP: PROCEDURE OPTIONS(MAIN); /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* SecureZIP for z/OS (TM), DATA COMPRESSION, VERSION 9.0 */ /* COPYRIGHT. 1989-2006 PKWARE Inc. ALL RIGHTS RESERVED. */ /* */ /* */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* Program: CALLZIPP */ /* */ /* This sample PL/I programs demonstrates the ability to call*/ /* PKZIP or PKUNZIP from an application program as a dynamic */ /* call (i.e., PKZIP and PKUNZIP are NOT linked into the */ /* program). There are three main variables used in calling */ /* PKZIP. First is the program variable PKZIP which contains*/ /* the name of program to call. The second variable is the */ /* parameters pass area MY_PARM with the length being left up*/ /* to the user. This example is using the pass area of 30 */ /* bytes. */ /* This Example is passing the parameter '- SHOW_SETTINGS'. */ /* If -NOSYSIN is also passed ('- SHOW_SETTINGS - NOSYSIN') */ /* PKZIP, would not read other parameters from SYSIN. This */ /* example it will read parameters from //SYSIN. */ /* */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* define the PKZIP variable return code save area */ DECLARE MY_RETURN_CODE FIXED BINARY(15); /* define PKZIP as an external variable with options */ DECLARE PKZIP ENTRY EXTERNAL('PKZIP') OPTIONS(RETCODE,ASSEMBLER); /* define the area for the parameters that are passed to PKZIP.*/ /* The length is left to user */ DECLARE MY_PARMS CHAR(30) VARYING;
339
DECLARE PLIRETV BUILTIN; DISPLAY ('Invoking Pkzip'); /* Set calling paramters and call PKZIP */ MY_PARMS ='-SHOW_SETTINGS'; /* Set the PARMS for PKZIP */ FETCH PKZIP; /* Dynamically fetch PKZIP */ CALL PKZIP(MY_PARMS); /* Call PKZIP passing the PARMS */ MY_RETURN_CODE=PLIRETV; /* save the Return code from PKZIP */ /* */ DISPLAY ('RETURNED FROM PKZIP RC=' || MY_RETURN_CODE); END;.
CALLZIPR Sample REXX Source to Call PKZIP
/* REXX ------------------------------------------------------------*/ /* NAME: PKZZIP */ /* PARMS: PKZIPLoad - The name of the current PKZIP Load data set. */ /* ARGPARMS - PKZIP passed parameters enclosed in quotes */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* SecureZIP for z/OS (TM), DATA COMPRESSION, VERSION 9.0 */ /* COPYRIGHT. 1989-2006 PKWARE Inc. ALL RIGHTS RESERVED. */ /* */ /* */ /* This sample REXX program demonstrates the ability to call */ /* PKZIP or PKUNZIP from an application program as a dynamic */ /* call. There are three main variables used in calling PKZIP */ /* First is the current PKZIP Load Library (PKZIPLoad) where */ /* PKZIP can be found. The second variable is the parameter */ /* pass area CALLPARMS where the parameters for PKZIP are */ /* passed to PKZIP program. This example uses an input argument */ /* to REXX to load the PARMS. This Example is passing the */ /* parameter '-ECHO -VERBOSE -SHOW_SETTINGS'. */ /* If -NOSYSIN is also passed ('- SHOW_SETTINGS - NOSYSIN'), */ /* PKZIP would not read other parameters from SYSIN. This */ /* example will read parameters from //SYSIN. */ /* */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /*-------------------------------------------------------------------*/ ARG PKZIPLoad ARGPARMS /* display the passed parameters */ LINE = 'REXX Sample to call PKZIP is starting' SAY LEFT(LINE,80) LINE = 'REXX Sample PKZIP Load lib is =' PKZIPLoad SAY LEFT(LINE,80) LINE = 'REXX Sample parameters =' ARGPARMS SAY LEFT(LINE,80) CALLPARMS = Strip(ARGPARMS,'B',"'") /* strip the quotes from PARMS */ /* If running from TSO other dataset will have to allocated */ /* "ALLOC FI(SYSPRINT) DA('*') SHR REUSE" */ /* "ALLOC FI(SYSABEND) DA('*') SHR REUSE" */ /* "ALLOC FI(SYSIN) DA('*') SHR REUSE" */ /* Could set other parameters such as CALLPARMS = '-SHOW_SETTINGS' */ "Call '"PKZIPLoad"(PKZIP)' '"CALLPARMS"'" LINE = 'REXX Sample to call PKZIP ended with Return=' RC
340
SAY LEFT(LINE,80) /* If running from TSO you will need to reset all the file assignments */ /* "FREE FI(SYSIN)" */ /* "FREE FI(SYSABEND)" */ /* "FREE FI(SYSPRINT)" */ .
CALLZC Sample C source program to call PKZIP
/* C -------------------------------------------------------------*/ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* SecureZIP for z/OS (TM), DATA COMPRESSION, VERSION 9.0 */ /* COPYRIGHT 1989-2006 PKWARE, Inc. ALL RIGHTS RESERVED. */ /* */ /* */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* Program: CALLZC */ /* */ /* This sample C programs demonstrates the ability to call PKZIP */ /* or PKUNZIP from an application program as a dynamic call (i.e. */ /* PKZIP and PKUNZIP are NOT linked into the program). There are */ /* three main variables used in calling PKZIP */ /* First is the program variable "fetch_module" which contains the */ /* name of program to fetch and call. The second variable is the */ /* parameters pass area "PKCommarea" with the length being */ /* calculated. This Example is passing the parameter: */ /* '-NOAPI -VERBOSE -SHOW_SETTINGS'. */ /* On return pass back the return code */ /* */ /* If -NOSYSIN is also passed ('-NOAPI -SHOW_SETTINGS -NOSYSIN') */ /* PKZIP, would not read other parameters from SYSIN. This */ /* example it will read parameters from //SYSIN. */ /* */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /*------------------------------------------------------------------*/ #include <stdio.h> #include <stdlib.h> #include <stdarg.h> #include <string.h> #define DOPRINTF printf /* define external ZIP Call function */ typedef int PKZIP_CALL(char *); #pragma linkage(PKZIP_CALL, OS) /* Define the Module to fetch and call */ char fetch_module [ 8] = {"PKZIP " } ; /* define MVS PKZIP Common pass area */ #pragma pack(packed) struct PK_Commarea { short int lenPKZBuffer; char PKZBuffer[5000]; } PKCommarea; char *pPKZCommands; #pragma pack(reset) /* A few common constants for testing */ char ProgamName1[] = "CALLZC "; char ZipParmNOSYSIN[] = "-NOSYSIN ";
341
char ZipParmNOAPI[] = "-NOAPI "; char ZipParmVIEW[9] = "-View "; int main(void) { PKZIP_CALL * pPKZIP = NULL; /* Initial call var */ int Func_RC = 0; /* Function Return Code */ DOPRINTF("%s using C Starting \n", ProgamName1); /* PKZIP is has not been fetched then fetch load module */ if (pPKZIP == NULL) { DOPRINTF("PKZIP API about to FETCH PKZIP \n"); pPKZIP = (PKZIP_CALL *) fetch(fetch_module); // Fetch PKZIP if (pPKZIP == NULL) { DOPRINTF("PKZIP API - Unable to FETCH %s module.\n", fetch_module); Func_RC = 12; return Func_RC; } else { DOPRINTF("%s API FETCHED ok. \n", fetch_module); } } /* end of pPKZIP == NULL */ /* setup the Parameters */ strcpy(PKCommarea.PKZBuffer, ZipParmNOSYSIN); strcpy(PKCommarea.PKZBuffer, ZipParmNOAPI); /* over lay NOSYSIN */ strcat(PKCommarea.PKZBuffer, "-VERBOSE " ); /* set the length of pass buffer */ PKCommarea.lenPKZBuffer = strlen(PKCommarea.PKZBuffer); DOPRINTF("Calling PKZIP with buffer Len=%d \n", PKCommarea.lenPKZBuffer); DOPRINTF("Calling Buffer=<%s> \n", PKCommarea.PKZBuffer); /* Now call the program by using the fetched function */ Func_RC = (*pPKZIP) ((char *)&PKCommarea); // Call PKZIP if (Func_RC != 0) { DOPRINTF("%s failed with return code:%d \n", fetch_module, Func_RC); return Func_RC; } DOPRINTF("%s API - returned OK \n", fetch_module); return Func_RC; } /* end of main func */
CALLZCPP Sample C++ program source to call PKZIP
/* C++ -----------------------------------------------------------*/ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* SecureZIP for z/OS (TM), DATA COMPRESSION, VERSION 9.0 */ /* COPYRIGHT 1989-2006 PKWARE, Inc. ALL RIGHTS RESERVED. */ /* */ /* */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* Program: CALLZCPP */ /* */ /* This sample C++ programs demonstrates the ability to call PKZIP */
342
/* or PKUNZIP from an application program as a dynamic call (i.e. */ /* PKZIP and PKUNZIP are NOT linked into the program). There are */ /* three main variables used in calling PKZIP */ /* First is the program variable "fetch_module" which contains the */ /* name of program to fetch and call. The second variable is the */ /* parameters pass area "PKCommarea" with the length being */ /* calculated. This Example is passing the parameter: */ /* '-NOAPI -VERBOSE -SHOW_SETTINGS'. */ /* On return pass back the return code */ /* */ /* If -NOSYSIN is also passed ('-NOAPI -SHOW_SETTINGS -NOSYSIN') */ /* PKZIP, would not read other parameters from SYSIN. This */ /* example it will read parameters from //SYSIN. */ /* */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /*-------------------------------------------------------------------*/ #include <stdio.h> #include <stdlib.h> #include <stdarg.h> #include <string.h> #define DOPRINTF printf /* define external ZIP Call function */ extern "OS" { typedef int typedefPKZIP( char *); } typedefPKZIP *pPKZIP = NULL; /* Define the Module to fetch and call */ char fetch_module [ 8] = {"PKZIP " } ; /* define MVS PKZIP Common pass area */ #pragma pack(packed) struct PK_Commarea { short int lenPKZBuffer; char PKZBuffer[5000]; } PKCommarea; char *pPKZCommands; #pragma pack(reset) /* A few common constants for testing */ char ProgamName1[] = "CALLZCPP "; char ZipParmNOSYSIN[] = "-NOSYSIN "; char ZipParmNOAPI[] = "-NOAPI "; char ZipParmVIEW[] = "-View "; int main(void) { int Func_RC = 0; /* Function Return Code */ DOPRINTF("%s using C++ Starting \n", ProgamName1); /* PKZIP is has not been fetched then fetch load module */ if (pPKZIP == NULL) { DOPRINTF("PKZIP API about to FETCH PKZIP \n"); pPKZIP = (typedefPKZIP *) fetch("PKZIP"); // Fetch PKZIP if (pPKZIP == NULL) { DOPRINTF("PKZIP API - Unable to FETCH %s module.\n", fetch_module); Func_RC = 12; return Func_RC; } else
343
{ DOPRINTF("%s API FETCHED ok. \n", fetch_module); } } /* end of pPKZIP == NULL */ /* setup the Parameters befeore call */ strcpy(PKCommarea.PKZBuffer, ZipParmNOAPI); /* over lay NOSYSIN */ strcat(PKCommarea.PKZBuffer, "-VERBOSE " ); strcat(PKCommarea.PKZBuffer, "-SHOW_SETTINGS "); // strcat(PKCommarea.PKZBuffer, "-ARCHIVE(WSS.OS400.TEST03.ZIP) "); // strcat(PKCommarea.PKZBuffer, ZipParmVIEW); // strcat(PKCommarea.PKZBuffer, "-UPDATE " ); // strcat(PKCommarea.PKZBuffer, "WSS.MVS.ASM($*) " ); /* set the length of pass buffer */ PKCommarea.lenPKZBuffer = strlen(PKCommarea.PKZBuffer); DOPRINTF("Calling PKZIP with buffer Len=%d \n", PKCommarea.lenPKZBuffer); DOPRINTF("Calling Buffer=<%s> \n", PKCommarea.PKZBuffer); /* Now call the program by using the function */ Func_RC = (*pPKZIP) ((char *)&PKCommarea); // Call PKZIP if (Func_RC != 0) { DOPRINTF("%s failed with return code:%d \n", fetch_module, Func_RC); return Func_RC; } DOPRINTF("%s API - returned OK \n", fetch_module); return Func_RC; } /* end of main func */
344
16 PKWARE PartnerLink: SecureZIP Partner
This chapter applies only to participants in the PKWARE PartnerLink program. Other readers may skip this section.
PKWARE PartnerLink enables a sponsor organization to give partner organizations that may not have SecureZIP for z/OS the SecureZIP Partner application so that sponsor and partner can use SecureZIP for z/OS to securely exchange ZIP archives.
About SecureZIP Partner for z/OS
SecureZIP Partner for z/OS is a special version of SecureZIP for z/OS. It provides most of the functionality of the full program but works only with archives created by (or for) a sponsor.
SecureZIP Partner has two modes of operation:
Read mode: Read mode enables SecureZIP functionality to extract files from a ZIP archive signed by a sponsor. In this mode, the program can decrypt and decompress files and authenticate digital signatures.
In Read mode, the program only extracts; it does not add files to a new or existing archive and does not compress, encrypt, or sign files. SecureZIP Partner extracts only archives digitally signed by a sponsor.
Write mode: Write mode enables SecureZIP functionality for adding files to a ZIP archive, including commands to compress, encrypt, and digitally sign files.
In Write mode, the program can create and update archives, but only for a designated PartnerLink sponsor and only if the sponsor provides certificates for SecureZIP Partner to use to encrypt. New or updated archives are automatically encrypted for sponsor recipients: only those recipients can decrypt and read the files.
SecureZIP Partner only does certificate-based encryption. It does not do passphrase-based encryption.
A single copy of the SecureZIP Partner software can process ZIP archives from multiple sponsors.
Note: SecureZIP Partner for z/OS was called SecureZIP for z/OS Reader/SecureLink prior to release 9.0 of SecureZIP for z/OS.
345
See the chapter relating to PartnerLink in the SecureZIP for z/OS System Administrator’s Guide for a description of administration and configuration activities unique to the SecureZIP Partner product.
If You Are a Sponsor: Sign the Central Directory A sponsor organization uses SecureZIP as usual to work with archives for, or from, a partner. There is just one special requirement when creating an archive for a partner: In order for the partner to be able to extract the archive you must sign the central directory of the archive using a certificate included in the Sponsor Distribution Package. A Sponsor Distribution Package is a package that PKWARE assembles for a sponsor to configure partners of that sponsor.
Terms and Acronyms Used in This Chapter
The PKWARE PartnerLink program introduces some new concepts and terminology:
Sponsor – An installation responsible for initiating and defining a PartnerLink sponsor-partner relationship with one or more other installations. A aponsor uses the full-featured SecureZIP product; a partner uses the special SecureZIP Partner for z/OS version.
Partner – An installation configured using a particular sponsor’s Sponsor Distribution Package (see below) to be a partner of that sponsor. A partner uses SecureZIP Partner for z/OS to work with archives from, or for, the sponsor.
Sponsor Distribution Package – A configuration package distributed to a partner on behalf of a sponsor to define the authorization requirements and provide the certificates needed to process ZIP archives from, or for, the sponsor. The package is digitally signed using a PKWARE-assigned certificate.
Sponsor File – A component file in a Sponsor Distribution Package
Sponsor Imprint – A unique digital representation of a registered sponsor-partner relationship within the PKWARE PartnerLink program. This may represent the unique identification of Distribution Package components or of ZIP archives being read.
Sponsor/Partner Registration ID – A unique registration number that identifies a particular sponsor-partner relationship
Read mode – The mode of SecureZIP Partner UNZIP processing that extracts archives from (and only from) a PartnerLink sponsor configured on the partner’s system
Write mode – The mode of SecureZIP Partner ZIP processing that creates an encrypted ZIP archive for a particular configured PartnerLink sponsor
FF – Acronym for full-featured SecureZIP operations, as distinct from those of SecureZIP Partner
346
PKWARE PartnerLink Program: Overview
The PKWARE PartnerLink program provides a straightforward, secure way for an organization to exchange sensitive information with outside partners.
A PartnerLink sponsor organization establishes a PartnerLink partner relationship with another organization. As a PartnerLink partner, the external organization receives the SecureZIP Partner program to use to decrypt and extract archives created by the sponsor using the full SecureZIP program. The partner can also use the program to create archives for the sponsor that only the sponsor can decrypt.
The SecureZIP Partner program used by a PartnerLink partner extracts archives only from a sponsor and creates and encrypts archives only for a sponsor.
Decrypting and Extracting Sponsor Data (Read Mode) When SecureZIP Partner is installed at a partner location, a sponsor can create, digitally sign, and encrypt SecureZIP secure containers (ZIP archives) for the partner. In Read mode, the SecureZIP Partner program verifies that the data file received has the appropriate signature from the sponsor and that the signature is valid. This confirms that the data is from the expected sender and that no tampering has occurred. The partner can then decrypt and extract the data.
347
Creating an Archive for a Sponsor If a sponsor has provided an encryption key, a partner can also use SecureZIP Partner (Write mode) to create encrypted ZIP archives for the sponsor. SecureZIP Partner automatically encrypts any data placed in an archive. The archive can then be transferred to media or transmitted to the sponsor electronically.
Requirements
License A license key is provided with the installation package for the system administrator to activate SecureZIP Partner for z/OS.
See the SecureZIP for z/OS System’s Administrator Guide for more information regarding license activation.
Operating Environment SecureZIP Partner for z/OS requires the same operating environment as full-featured SecureZIP for z/OS.
Sponsoring Configuration In order to fully process ZIP Archives, the system administrator for SecureZIP Partner for z/OS must install one or more Sponsor Distribution Packages and provide the corresponding run-time configuration information for the ZIP and UNZIP jobs to use. The installed Sponsor Distribution Package determines which archive signatures are approved for Read mode Extract processing and defines the list of sponsor recipients for whom SecureZIP Partner encrypts new archives.
Functional Overview
SecureZIP Partner for z/OS enables a PartnerLink partner to exchange ZIP archives with a sponsor. A Sponsor Distribution Package provides the partner installation with qualifying controls for processing ZIP archives received from or created for a sponsor. Multiple sponsor
348
profiles with unique processing requirements can be configured to support exchanges with multiple PKWARE PartnerLink sponsors.
A given sponsor profile defines the UNZIP and ZIP capabilities for a partner. In a given sponsor-partner relationship, a partner operates in Read mode to extract archives and in Write mode to create archives.
See the SecureZIP for z/OS System Administrator’s Guide for information on installing Sponsor Distribution Packages.
General Restrictions Although many features of full-featured SecureZIP for z/OS are also available to SecureZIP Partner for z/OS, some limitations apply for these products.
SecureZIP Partner for z/OS (Read mode) can only open a ZIP archive that has been digitally signed by a qualified and configured sponsor, as specified in the Sponsor Distribution Package.
SecureZIP Partner for z/OS (Write mode) can only generate a ZIP archive that is encrypted, using certificate-based encryption, for sponsor recipients for whom the sponsor has provided certificates.
Attempts to use features that require operational characteristics outside of the bounds set above are rejected or ignored.
SecureZIP Partner (Read mode) Processing
The following features are provided by SecureZIP Partner when operating in Read mode:
An AUTHCHK(Archive) is automatically performed whenever a ZIP archive is opened, except in the following cases:
o An AUTHCHK(ARCHIVE) is requested manually
o Any form of View action
o A TEST action without any form of AUTHCHK request
A TAMPERCHECK policy will always be enforced for authentication, regardless of the SecureZIP configuration policy settings.
The certificate authority trust chain will automatically be honored from the installed and configured Sponsor Distribution Package during archive authentication even if the trusted root certificate is not installed in the local certificate ROOT store.
If the sponsor also signed files in an archive with the same certificate used to sign the archive central directory, the same certificate authority trust chain used to authenticate the archive signature is used to authenticate signatures on the files.
Restrictions The following limitations or special behavior applies when SecureZIP Partner for z/OS extracts (Read mode) :
349
Archive types (such as GZIP) that do not support signing the archive central directory are not available.
When AUTHCHK(ARCHIVE) is optionally requested for Test or View processing, Read-mode processing is activated to use Sponsor Distribution Package components in the configured certificate store.
An archive view will provide an encryption recipient count but not a detailed list of the recipients from the installed Sponsor Distribution Package. (Individual public-key certificate files must installed to the SecureZIP certificate store as CER entries for recipient list information to be cross-referenced for display.) However, a Sponsor Distribution Package informational display may be done for the associated SecureZIP Partner sponsor recipient list to determine which specific recipients are included for encryption.
Archive Authentication Settings The archive authentication that is automatically performed when a ZIP archive is opened for extract processing uses one or more Sponsor Authentication Configuration Settings to reference an installed Sponsor Authentication File in the certificate store. This is accomplished by including one or more –{SPONSOR_AUTH=…} configuration settings through an INCLUDE_CMD command. (See the section on configured sponsor package components in the SecureZIP System Administrator’s Guide.)
At least one –{SPONSOR_AUTH=…} command is required to access a ZIP archive for extract processing.
If more than one Sponsor Authentication Configuration Setting command is provided, then the archive authentication will accept an archive from any of the represented sponsors.
Decryption Certificate Selection RECIPIENT private-key/certificate selection follows the rules for full-featured SecureZIP for z/OS local certificate store administration and operations.
File Signature Authentication Certificate Selection In addition to supporting AUTHCHK(FILES) with implicit reference to the AUTHCHK(ARCHIVE) certificate validation, separate and distinct file signatory validation can be performed outside of the configured Sponsor Distribution Package. However, this operation is allowed only for files in a sponsor-provided data archive that have signatures for which certificates are not included in the Sponsor Distribution Package.
Public-key certificate files supporting file signature authentication can be supplied through the full-featured SecureZIP for z/OS CER certificate types in the local certificate store.
SecureZIP Partner (Write mode) Processing
With SecureZIP Partner for z/OS, a sponsor-authorized partner can generate a ZIP archive for the sponsor. Data files placed in the created archive are encrypted for a sponsor-
350
designated set of certificate-based recipients. The following special features are provided by SecureZIP Partner in Write mode:
Unless otherwise specified, a minimum encryption method of AES128 is set for newly encrypted files.
All recipients defined in the sponsor-defined recipient package (as configured from the Sponsor Distribution Package) are included in the encryption request.
Recipients identified in the sponsor-defined recipient package are subject to the SecureZIP VALENCRYPT policy settings in the certificate store configuration. Individual recipients not passing the designated policy attributes are eliminated from encryption processing.
The certificate authority trust chain from the installed and configured Sponsor Distribution Package is automatically honored for the designated recipients even if the trusted root certificate is not installed in the local certificate store ROOT.
When a sponsor-source ZIP archive is used as input to create an updated target archive, Read-mode operating characteristics are activated while processing the input archive.
When a sponsor-source ZIP archive is used as input to create an updated target archive, files copied from the original archive retain their original form.
Newly created archives may be Viewed using SecureZIP Partner.
Restrictions The following features are not available or have limitations for SecureZIP Partner for z/OS (Write mode):
GZIP output is not available.
Self-extracting archives cannot be created.
An encryption method for supported recipient-based encryption must be used (“Standard” is not supported).
Passphrase-based encryption for new archives is not available.
Encryption is only permitted for sponsor-provided keys.
All archive creation actions require a qualified response recipient configuration as provided by the Sponsor Distribution Package.
The Directory Integration feature, providing LDAP access to public-key certificates for encryption and related functions, is not available.
An archive can be created and encrypted only for recipients associated with a single sponsor; an archive cannot be created for multiple sponsors, although note that multiple public-key certificates can be included by a given sponsor in a Sponsor Distribution Package. This implementation rules out the use of DB: and LDAP: request formats for the RECIPIENT command.
An output archive with using FILENAME_ENCRYPTION can be created in accordance with the qualified sponsor recipient keys. However, because SecureZIP Partner can
351
create and encrypt archives only for a sponsor, a partner cannot update a filename-encypted archive from a sponsor for the partner.
Encryption Certificate Selection RECIPIENT public-key/certificate selection is predefined by the Sponsor Distribution Package. The SecureZIP for z/OS local certificate store is extended to support sponsor-provided encryption keys. The SecureZIP Partner (Write mode) RECIPIENT command is limited to accessing only those public-keys supplied in the SecureZIP Partner Authorized Recipient File.
When a RECIPIENT DB: request is made, only index records associated with SecureZIP Partner (Write mode) (type code “SLNK”) are searched.
Archive Authentication Settings The archive authentication that is automatically performed when a ZIP archive is opened for SecureZIP Partner extract processing (Read mode) uses one or more Sponsor Authentication Configuration Settings to reference an installed Sponsor Authentication File in the certificate store. This is accomplished by including one or more –{SPONSOR_AUTH=…} configuration settings through an INCLUDE_CMD command. (See the section on configured sponsor package components in the SecureZIP System Administrator’s Guide.)
At least one –{SPONSOR_AUTH=…} command is required to access a ZIP archive for extract processing. Creation of a new ZIP archive does not require a Sponsor Authenticaion Configuration SPONSOR_AUTH command because there is no input archive to authenticate.
If more than one Sponsor Authentication Configuration Setting command is provided, then the archive authentication will accept an archive from any of the represented sponsors.
352
A (reserved)
This section is intentionally left blank.
353
B Sample Jobstreams
Example 1: Zip PDS to an Archive
JCL Used
//SAMPZIP1 JOB (XXXX),SAMPZIP1, // CLASS=B, // MSGCLASS=Q, // NOTIFY=&SYSUID, // REGION=8M //****************************************************************** //* Sample job stream to ZIP pds file "SYS1.MACLIB" to an * //* archive of "PKWARE.MACLIB.ARCHIVE" * //****************************************************************** //* //ZIP1 EXEC PGM=PKZIP,PARM='-ECHO ' //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKWARE.MACLIB.ARCHIVE) -ACTION(ADD) SYS1.MACLIB /* //
Resulting Output
ZPAM030I OUTPUT Archive opened: PKWARE.MACLIB.ARCHIVE ZPAM253I ADDED File SYS1.MACLIB(ABEND) ZPAM254I as SYS1/MACLIB/ABEND ZPAM255I (DEFLATED 78%/78%) ZPAM253I ADDED File SYS1.MACLIB(ACB) ZPAM254I as SYS1/MACLIB/ACB ZPAM255I (DEFLATED 77%/77%) ZPAM253I ADDED File SYS1.MACLIB(ACBVS) ZPAM254I as SYS1/MACLIB/ACBVS ZPAM255I (DEFLATED 78%/77%) ZPAM253I ADDED File SYS1.MACLIB(ACI) ZPAM254I as SYS1/MACLIB/ACI
354
ZPAM255I (DEFLATED 73%/72%) . . . . . . . . . . . . . . . . . . . . . . . . . ZPAM253I ADDED File SYS1.MACLIB(YREGS) ZPAM254I as SYS1/MACLIB/YREGS ZPAM255I (DEFLATED 83%/83%) ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Example 2: Zip PDS to an Archive
JCL Used
//SAMPZIP2 JOB (XXXX),SAMPZIP2, // CLASS=B, // MSGCLASS=Q, // NOTIFY=&SYSUID, // REGION=8M //****************************************************************** //* Sample job stream to ZIP pds file "SYS1.MACLIB" to an * //* archive of "PKWARE.MACLIB.ARCHIVE" * //* * //* The second qualifier of the output member(s) will be * //* changed to "MYLIB" per the ZIPPED_DSN command. * //****************************************************************** //* //ZIP2 EXEC PGM=PKZIP,PARM='-ECHO ' //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKWARE.MACLIB.ARCHIVE) -ACTION(ADD) -ZIPPED_DSN(*.MACLIB(*),*/MYLIB/*) SYS1.MACLIB /* //
355
Resulting Output
ZPAM030I OUTPUT Archive opened: PKWARE.MACLIB.ARCHIVE ZPAM253I ADDED File SYS1.MACLIB(ABEND) ZPAM254I as SYS1/MYLIB/ABEND ZPAM255I (DEFLATED 78%/78%) ZPAM253I ADDED File SYS1.MACLIB(ACB) ZPAM254I as SYS1/MYLIB/ACB ZPAM255I (DEFLATED 77%/77%) ZPAM253I ADDED File SYS1.MACLIB(ACBVS) ZPAM254I as SYS1/MYLIB/ACBVS ZPAM255I (DEFLATED 78%/77%) ZPAM253I ADDED File SYS1.MACLIB(ACI) ZPAM254I as SYS1/MYLIB/ACI ZPAM255I (DEFLATED 73%/72%) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZPAM253I ADDED File SYS1.MACLIB(YREGS) ZPAM254I as SYS1/MYLIB/YREGS ZPAM255I (DEFLATED 83%/83%) ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Example 3: Zip VSAM KSDS to an Archive
JCL Used
//SAMPZIP3 JOB (XXXX),SAMPZIP3, // CLASS=B, // MSGCLASS=Q, // NOTIFY=&SYSUID, // REGION=8M //****************************************************************** //* Sample job stream to ZIP VSAM KSDS file "PKWARE.SAMPLE.KSDS" to a * //* archive of "PKWARE.VSAMKSDS.ARCHIVE". * //* * //* "ARCHIVE_VOLUMES" will write the Archive to the volume * //* specified. * //* * //* "COMPRESSION_LEVEL(STORE)" requests NO compression. * //****************************************************************** //* //ZIP3 EXEC PGM=PKZIP,PARM='-ECHO ' //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKWARE.VSAMKSDS.ARCHIVE) -ACTION(ADD) -ARCHIVE_VOLUMES(PKWARE) -COMPRESSION_LEVEL(STORE) PKWARE.SAMPLE.KSDS /* //
356
Resulting output
ZPAM030I OUTPUT Archive opened: PKWARE.VSAMKSDS.ARCHIVE ZPAM253I ADDED File PKWARE.SAMPLE.KSDS ZPAM254I as PKWARE/SAMPLE/KSDS ZPAM255I (STORED 0%/ 2%) ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Example 4: Summary View of a Dataset
JCL Used
//SAMVIEW1 JOB (XXXX),SAMVIEW1, // CLASS=B, // MSGCLASS=Q, // NOTIFY=&SYSUID, // REGION=8M //****************************************************************** //* Sample job stream to do a summary VIEW of dataset * //* "PKWARE.MACLIB.ARCHIVE". * //****************************************************************** //* //VIEW1 EXEC PGM=PKZIP,PARM='-ECHO ' //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKWARE.MACLIB.ARCHIVE) -ACTION(VIEW) /* //
Resulting output
ZPAM030I INPUT Archive opened: PKWARE.MACLIB.ARCHIVE ZPAM014I There are 1539 file(s) in the input Archive. ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE Inc. ZPAM013I ****************************************************************************************************** ZPAM015I Length Method Size Ratio Date Time CRC-32 Name ZPAM016I --------------- ------------ --------------- ----- ---------- ----- ----------------------------------- ZPAM017I 12,957 DEFLATE-NORM 2,856 78% 08/09/2005 11:14 36BDC0D4 SYS1/MYLIB/ABEND ZPAM017I 6,315 DEFLATE-NORM 1,462 77% 08/09/2005 11:14 1E1A020B SYS1/MYLIB/ACB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZPAM017I 2,543 DEFLATE-NORM 433 83% 08/09/2005 11:16 E0B4A859 SYS1/MYLIB/YREGS ZPAM018I --------------- --------------- ----- ZPAM019I 111,359,012 17,822,596 84% ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
357
Example 5: Summary View of a Dataset
JCL Used
//SAMVIEW2 JOB (XXXX),SAMVIEW2, // CLASS=B, // MSGCLASS=Q, // NOTIFY=&SYSUID, // REGION=8M //****************************************************************** //* Sample job stream to do a summary VIEW of dataset * //* "PKWARE.MACLIB.ARCHIVE". * //* * //* A request is also made to do a "BRIEF" which will * //* eliminate the "CRC-32" information from being displayed.* //****************************************************************** //* //VIEW2 EXEC PGM=PKZIP,PARM='-ECHO ' //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKWARE.MACLIB.ARCHIVE) -ACTION(VIEWBRIEF) /* //
Resulting output
ZPAM030I INPUT Archive opened: PKWARE.MACLIB.ARCHIVE
ZPAM014I There are 1539 file(s) in the input Archive. ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE Inc. ZPAM013I ******************************************************************************************************* ZPAM020I Length Method Size Ratio Date Time Name ZPAM021I --------------- ------------ --------------- ----- ---------- ----- ----------------------------------- ZPAM017I 12,957 DEFLATE-NORM 2,856 78% 08/09/2005 11:14 SYS1/MYLIB/ABEND ZPAM017I 6,315 DEFLATE-NORM 1,462 77% 08/09/2005 11:14 SYS1/MYLIB/ACB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZPAM017I 2,543 DEFLATE-NORM 433 83% 08/09/2005 11:16 SYS1/MYLIB/YREGS ZPAM018I --------------- --------------- ----- ZPAM019I 111,359,012 17,822,596 84% ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
358
Example 6: View with Detail of an Archive
JCL Used
//SAMVIEW3 JOB (XXXX),SAMVIEW3, // CLASS=B, // MSGCLASS=Q, // NOTIFY=&SYSUID, // REGION=8M //****************************************************************** //* Sample job stream to do a VIEW with a DETAIL listing of the * //* entries in "PKWARE.MACLIB.ARCHIVE". * //* * //* A request is also made to do a "NAME" which will * //* do the listing in Data Set Name (Ascending) sequence. * //****************************************************************** //* //VIEW3 EXEC PGM=PKZIP,PARM='-ECHO ' //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKWARE.MACLIB.ARCHIVE) -ACTION(VIEWDETAILNAME) /* //
Resulting output
ZPAM030I INPUT Archive opened: PKWARE.MACLIB.ARCHIVE ZPAM014I There are 1539 file(s) in the input Archive. ZPAM012I ZIP comment: SecureZIP for z/OS by PKWARE Inc. ZPAM013I ZPAM001I Filename: SYS1/MYLIB/ABEND ZPAM002I File type: TEXT ZPAM003I Date/Time: 09-AUG-2005 11:14:34 ZPAM004I Compression Method: DEFLATE -NORMAL ZPAM005I Compressed Size: 2,856 ZPAM006I Uncompressed Size: 12,957 ZPAM007I 32-bit CRC: 36BDC0D4 ZPAM008I Created by: PKZIP for MVS 5.5 * - 2.x compatible ZPAM009I Needed to extract: ZipSpec 2.0 ZPAM301I File Type: NONVSAM PDS ZPAM302I File PDS Directory Blocks: 200 ZPAM303I File Record Format: FB ZPAM304I File Allocation Type: TRK ZPAM305I File Primary Space Allocated: 2245 ZPAM306I File Secondary Space Allocated: 90 ZPAM307I File Record Size: 80 ZPAM308I File Block Size: 6160 ZPAM309I File Volume(s) Used: PKWARE ZPAM310I File Creation Date: 2005/07/27 ZPAM311I File Referenced Date: 2005/08/09 ZPAM312I File PDS Extended Directory Information: DIRECTORY INFORMATION FOLLOWS LENGTH=000004 000000 52540647 00000000 00000000 00000000 |................| ZPAM313I PDS member TTRKZC: 010E07000002 ZPAM013I ZPAM001I Filename: SYS1/MYLIB/ACB ZPAM002I File type: TEXT ZPAM003I Date/Time: 09-AUG-2005 11:14:34
359
ZPAM004I Compression Method: DEFLATE -NORMAL ZPAM005I Compressed Size: 1,462 ZPAM006I Uncompressed Size: 6,315 ZPAM007I 32-bit CRC: 1E1A020B ZPAM008I Created by: PKZIP for MVS 5.5 * - 2.x compatible ZPAM009I Needed to extract: PKUNZIP 2.0 ZPAM301I File Type: NONVSAM PDS ZPAM302I File PDS Directory Blocks: 200 ZPAM303I File Record Format: FB ZPAM304I File Allocation Type: TRK ZPAM305I File Primary Space Allocated: 2245 ZPAM306I File Secondary Space Allocated: 90 ZPAM307I File Record Size: 80 ZPAM308I File Block Size: 6160 ZPAM309I File Volume(s) Used: PKWARE ZPAM310I File Creation Date: 2005/07/27 ZPAM311I File Referenced Date: 2005/08/09 ZPAM312I File PDS Extended Directory Information: DIRECTORY INFORMATION FOLLOWS LENGTH=000004 000000 71620002 00000000 00000000 00000000 |................| ZPAM313I PDS member TTRKZC: 004307000002 ZPAM013I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZPAM001I Filename: SYS1/MYLIB/YREGS ZPAM002I File type: TEXT ZPAM003I Date/Time: 09-AUG-2005 11:16:24 ZPAM004I Compression Method: DEFLATE -NORMAL ZPAM005I Compressed Size: 433 ZPAM006I Uncompressed Size: 2,543 ZPAM007I 32-bit CRC: E0B4A859 ZPAM008I Created by: PKZIP for MVS 5.5 * - 2.x compatible ZPAM009I Needed to extract: ZipSpec 2.0 ZPAM301I File Type: NONVSAM PDS ZPAM302I File PDS Directory Blocks: 200 ZPAM303I File Record Format: FB ZPAM304I File Allocation Type: TRK ZPAM305I File Primary Space Allocated: 2245 ZPAM306I File Secondary Space Allocated: 90 ZPAM307I File Record Size: 80 ZPAM308I File Block Size: 6160 ZPAM309I File Volume(s) Used: PKWARE ZPAM310I File Creation Date: 2005/07/27 ZPAM311I File Referenced Date: 2005/08/09 ZPAM312I File PDS Extended Directory Information: DIRECTORY INFORMATION FOLLOWS LENGTH=000004 000000 71690198 00000000 00000000 00000000 |...q............| ZPAM313I PDS member TTRKZC: 00AC09000002 ZPAM013I ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
360
Example 7: Unzip an Archive to PDS
JCL Used
//SAMUNZP1 JOB (XXXX),SAMUNZP1, // CLASS=B, // MSGCLASS=Q, // NOTIFY=&SYSUID, // REGION=8M //****************************************************************** //* Sample job stream to UNZIP a zipped PDS file * //* archive of "PKWARE.MACLIB.ARCHIVE" back to it's original * //* content. * //* * //* The "FILE_EXTENSION(NAMEFILE)" will use the last * //* component of the ZIPPED name as the PDS member name. * //****************************************************************** //* //UNZIP1 EXEC PGM=PKUNZIP,PARM='-ECHO ' //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSIN DD * -FILE_EXTENSION(NAMEFILE) -ARCHIVE_DSN(PKWARE.MACLIB.ARCHIVE) /* //
Resulting output
ZPAM030I INPUT Archive opened: PKWARE.MACLIB.ARCHIVE ZPEX002I SYS1/MACLIB/ABEND ZPEX003I Extracted to SYS1.MACLIB(ABEND) ZPEX002I SYS1/MACLIB/ACB ZPEX003I Extracted to SYS1.MACLIB(ACB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZPEX002I SYS1/MACLIB/YREGS ZPEX003I Extracted to SYS1.MACLIB(YREGS) ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Example 8: Unzip an Archive to PDS
JCL Used
//SAMUNZP2 JOB (XXXX),SAMUNZP2, // CLASS=B, // MSGCLASS=Q, // NOTIFY=&SYSUID, // REGION=8M //****************************************************************** //* Sample job stream to UNZIP a zipped PDS file * //* archive of "PKWARE.MACLIB.ARCHIVE" back to it's original * //* content. *
361
//* * //* The "FILE_EXTENSION(NAMEFILE)" will use the last * //* component of the ZIPPED name as the PDS member name. * //* * //* The "UNZIPPED_DSN" is being used to change the HLQ of * //* the file. While it was ZIPPED as "SYS1" it will be * //* UNZIPPED as "SYS2". * //****************************************************************** //* //UNZIP2 EXEC PGM=PKUNZIP,PARM='-ECHO ' //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSIN DD * -UNZIPPED_DSN(SYS1,SYS2) -FILE_EXTENSION(NAMEFILE) -ARCHIVE_DSN(PKWARE.MACLIB.ARCHIVE) /*
Resulting output
ZPAM030I INPUT Archive opened: PKWARE.MACLIB.ARCHIVE ZPEX002I SYS1/MACLIB/ABEND ZPEX003I Extracted to SYS2.MACLIB(ABEND) ZPEX002I SYS1/MACLIB/ACB ZPEX003I Extracted to SYS2.MACLIB(ACB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZPEX002I SYS1/MACLIB/YREGS ZPEX003I Extracted to SYS2.MACLIB(YREGS) ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
Example 9: Unzip an Archive to VSAM KSDS
JCL Used
//SAMUNZP3 JOB (XXXX),SAMUNZP3, // CLASS=B, // MSGCLASS=Q, // NOTIFY=&SYSUID, // REGION=8M //****************************************************************** //* Sample job stream to UNZIP a zipped VSAM file * //* archive of "PKWARE.VSAMKSDS.ARCHIVE" back to it's original * //* VSAM structure. * //****************************************************************** //* //UNZIP3 EXEC PGM=PKUNZIP,PARM='-ECHO ' //STEPLIB DD DISP=SHR,DSN=PKWARE.MVS.LOAD //SYSPRINT DD SYSOUT=* //SYSABEND DD SYSOUT=* //SYSIN DD * -ARCHIVE_DSN(PKWARE.VSAMKSDS.ARCHIVE) /* //
362
Resulting output
ZPAM030I INPUT Archive opened: PKWARE.VSAMKSDS.ARCHIVE ZPEX002I PKWARE/SAMPLE/KSDS ZPEX003I Extracted to PKWARE.SAMPLE.KSDS ZPMT002I PKZIP processing complete. RC=00000000 0(Dec)
363
C 3490 Installation JCL (COPYCART)
//pkwaretp JOB (xxxxxx),'xxx', <=== // CLASS=x, <=== // MSGCLASS=x, <=== // MSGLEVEL=(1,1), // NOTIFY=&SYSUID, // REGION=6144K, // TIME=1440 //* //******************************************************************* //* * //* All lines with '<==='; "lowercase" values will require * //* review & change. * //* * //* In ISPF use the < CHANGE ALL > command to edit * //* the lower case parameter selections to the value * //* you select, for instance if UNIT=SYSDA is valid * //* for JCL enter < CHANGE ALL sysda SYSDA > to * //* replace all occurrences in this member. * //* * //* CHANGE ALL: * //* Edit the Job Card as needed. * //* * //* pkware.mvspkware.mvs - to the ALIAS for SecureZIP MVS files * //* * //* disk - to the UNIT type for PDS files * //* * //* sysda - to the UNIT type for temporary files * //* * //* seczip1 - to the Volume Serial Number of the install tape * //* * //* tape - to the UNIT type for tape * //* * //* volume - to the VOLUME for the PDS files * //* * //******************************************************************* //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.CEXEC" TO CUSTOMERS DASD<== * //******************************************************************* //JS010 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.CEXEC, // UNIT=tape,LABEL=(,SL), <=== // DISP=OLD,VOL=(,RETAIN,,,SER=seczip1) <=== //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.CEXEC, <===
364
// DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(1,1,52)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.HELP" TO CUSTOMERS DASD<== * //******************************************************************* //JS020 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.HELP, // VOL=(,RETAIN,REF=*.JS010.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(2,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.HELP, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.INSTLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS030 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.INSTLIB, // VOL=(,RETAIN,REF=*.JS020.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(3,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.INSTLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,52)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.LOAD" TO CUSTOMERS DASD<== * //******************************************************************* //JS040 EXEC PGM=IEBCOPY
365
//* //SYSUT1 DD DSN=PKWARE.MVS.LOAD, // VOL=(,RETAIN,REF=*.JS030.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(4,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.LOAD, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(50,10,52)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.MACLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS050 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.MACLIB, // VOL=(,RETAIN,REF=*.JS040.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(5,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.MACLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,52)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SPKZCLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS060 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SPKZCLIB, // VOL=(,RETAIN,REF=*.JS050.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(6,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SPKZCLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(1,1,52)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD *
366
COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SPKZMLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS070 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SPKZMLIB, // VOL=(,RETAIN,REF=*.JS060.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(7,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SPKZMLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(1,1,52)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SPKZPLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS080 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SPKZPLIB, // VOL=(,RETAIN,REF=*.JS070.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(8,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SPKZPLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(1,1,52)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SPKZTLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS090 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SPKZTLIB, // VOL=(,RETAIN,REF=*.JS080.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(9,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SPKZTLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(1,1,52)), // UNIT=disk, <=== // VOL=SER=volume <===
367
//* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SPKZSLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS100 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SPKZSLIB, // VOL=(,RETAIN,REF=*.JS090.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(10,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SPKZSLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(1,1,52)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(5,5)) //SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(5,5)) //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.INSTLIB2" TO CUSTOMERS DASD<== * //******************************************************************* //JS110 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.INSTLIB2, // VOL=(,RETAIN,REF=*.JS100.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(11,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.INSTLIB2, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(2,1,5)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(5,5)) //SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(5,5)) //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 //* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.MCS" TO CUSTOMERS DASD<== * //******************************************************************* //JS120 EXEC PGM=IEBGENER //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.MCS, // VOL=(,RETAIN,REF=*.JS110.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(12,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.MCS, <===
368
// DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(2,9)), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD DUMMY /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DLOAD" TO CUSTOMERS DASD<== * //******************************************************************* //JS130 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DLOAD, // VOL=(,RETAIN,REF=*.JS120.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(13,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DLOAD, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DCEXE" TO CUSTOMERS DASD<== * //******************************************************************* //JS140 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DCEXE, // VOL=(,RETAIN,REF=*.JS130.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(14,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DCEXE, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DCLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS150 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DCLIB, // VOL=(,RETAIN,REF=*.JS140.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(15,SL), <===
369
// DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DCLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DHELP" TO CUSTOMERS DASD<== * //******************************************************************* //JS160 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DHELP, // VOL=(,RETAIN,REF=*.JS150.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(16,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DHELP, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DINST" TO CUSTOMERS DASD<== * //******************************************************************* //JS170 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DINST, // VOL=(,RETAIN,REF=*.JS160.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(17,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DINST, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DPLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS180 EXEC PGM=IEBCOPY
370
//* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DPLIB, // VOL=(,RETAIN,REF=*.JS170.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(18,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DPLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DMACL" TO CUSTOMERS DASD<== * //******************************************************************* //JS190 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DMACL, // VOL=(,RETAIN,REF=*.JS180.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(19,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DMACL, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DMLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS200 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DMLIB, // VOL=(,RETAIN,REF=*.JS190.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(20,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DMLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /*
371
//******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DTLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS210 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DTLIB, // VOL=(,RETAIN,REF=*.JS200.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(21,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DTLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DINS2" TO CUSTOMERS DASD<== * //******************************************************************* //JS220 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DINS2, // VOL=(,RETAIN,REF=*.JS210.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(22,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DINS2, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=* //* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //******************************************************************* //* ==>RESTORE "pkware.mvspkware.mvs.SMP.DSLIB" TO CUSTOMERS DASD<== * //******************************************************************* //JS230 EXEC PGM=IEBCOPY //* //SYSUT1 DD DSN=PKWARE.MVS.SMP.DSLIB, // VOL=(,RETAIN,REF=*.JS220.SYSUT1), // UNIT=(tape,,DEFER),LABEL=(23,SL), <=== // DISP=OLD //* //SYSUT2 DD DSN=pkware.mvspkware.mvs.SMP.DSLIB, <=== // DISP=(NEW,CATLG,DELETE), // SPACE=(CYL,(10,10,99),RLSE), // UNIT=disk, <=== // VOL=SER=volume <=== //* //SYSUT3 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //SYSUT4 DD UNIT=sysda,SPACE=(CYL,(5,5)) <=== //* //SYSPRINT DD SYSOUT=*
372
//* //SYSIN DD * COPY INDD=SYSUT1,OUTDD=SYSUT2 /* //
373
D Making Code Page Translate Tables (EDCICONV)
Translation Tables
Text data is represented by one of two base English character encoding schemes: EBCDIC or ASCII. In each scheme, individual alphanumeric characters are assigned an internal numeric code within the range of 0-255 (hexadecimal 00-FF). Although most of the same characters (e.g., A-Z, a-z, 0-9) are contained in the EBCDIC and ASCII character sets, different numeric code assignments are used for each. PKZIPz™ translates EBCDIC characters into the ASCII character set, which is the standard set used by ZIP compatible products to store text data.
Situations may arise in unique platform interchanges or when working with text files from different countries when the default translation table is not adequate. Users may select any available translation table by using the TRANSLATE_TABLE_DATA command.
EBC#8859 is the default if TRANSLATE_TABLE_DATA is not specified. If a table other than ASCII is used often, you can make it the default, and eliminate the need to use the TRANSLATE_TABLE_DATA command each time.
Code Page Support
PKZIPz provides certain “ready to use” translation tables commonly used in an IBM EBCDIC environment. These tables are provided “as is” and are not supported as part of PKZIPz. It is the user’s responsibility to ensure that data translation mapping satisfies their requirements. Additional source tables (as described under “International Code Page Support” in this Appendix) are provided as samples in the product install library for use by installations with special translation needs.
There are many other specialized character sets available to the user community. OS/390 and zOS provide a data translation feature, ICONV, that can be used to generate translation tables compatible with PKZIPz.
374
International Code Page Support
The source tables for the following international code pages are provided in PKZIPz. They are provided in the INSTLIB library as member name TRTxxyy. The suffix xx = LANGUAGE and suffix yy = ASCII OR EURO ASCII.
For example, to translate Spanish to Euro ASCII and back you would use table TRTEJAI.
Language EBCDIC Code Page
ASCII Code Page
EURO/ASCII Code Page
EBCDIC Code Set ID
ASCII Code Set ID
EURO/ ASCII CODE Set ID
Table Name ASCII
Table Name EURO
German 273 850 858 EB AA AI TRTEBAA TRTEBAI
Spanish 284 850 858 EJ AA AI TRTEJAA TRTEJAI
Portuguese 282 850 858 EI AA AI TRTEIAA TRTEIAI
Italian 280 850 858 EG AA AI TRTEGAA TRTEGAI
Danish 277 850 858 EE AA AI TRTEEAA TRTEEAI
Norwegian 277 850 858 EE AA AI TRTEEAA TRTEEAI
Swedish 278 850 858 EF AA AI TRTEFAA TRTEFAI
Finnish 278 850 858 EF AA AI TRTEFAA TRTEFAI
French 297 850 858 EM AA AI TRTEMAA TRTEMAI
English UNIX
IBM 1047
ISO 8859-1
EBC#8859
English PC IBM 1047
IBM 850
EBC#850
Code Conversion Utility
The ICONV utility reads characters from the input file, converts them from “fronCodeSet” encoding to “toCodeSet” encoding, and writes them to the output file.
EDCICONV is a procedure provided with the IBM Language Extensions product that is used to invoke the ICONV functions. Documentation about the ICONV functions is contained within the procedure and is fully documented in IBM's z/OS V1R1.0 C/C++ Programming Guide.
The following sample job (found in PKWARE.MVS.INSTLIB(MAKETRT) executes the EDCICONV procedure twice to perform codeset translations and then combines the translation table source into a single source table that can be assembled for use by PKZIPz.
In the example, the first step translates a known table from French to the Euro codeset and the second step converts it back. The CODEIN table is provided in the PKZIPz install library and has all values from x'00' to x'ff'. The parameter FROMC= is the 2 character designator for the "from" codeset and the parameter TOC= is the 2 character designator for the "to" codeset. The third step executes a ZIP utility, BUILDTAB, which takes the two codesets that were created and generates assembler language source for a table that can be assembled, linked and subsequently used with PKZIPz.
375
The parameter required for this step is the 2 character designator for the "from" codeset followed by the 2 character designator for the "to" codeset.
Translate Table Generation
Member ASMTRTS in INSTLIB will assemble the generated source and link it as a translate table in the PKZIPz load library.
Sample Job
//JOBNAME JOB (ACCT),'PRGRMR',CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1), // NOTIFY=&SYSUID,TIME=1440,REGION=6144K //* // JCLLIB ORDER=CEE.SCEEPROC //* //* step 1 uses the ICONV function of LE to create the codeset for //* converting from French in this example to the Euro codeset //* //STEP1 EXEC EDCICONV, // INFILE=PKWARE.MVS.INSTLIB(CODEIN), // OUTFILE=USERID.TEST.CODESETS(EMAI), // FROMC=IBM-297,TOC=IBM-858 //* //* step 2 uses the ICONV function of LE to create the codeset for //* converting from Euro in this example to the French codeset //* //STEP2 EXEC EDCICONV, // INFILE=PKWARE.MVS.INSTLIB(CODEIN), // OUTFILE=USERID.TEST.CODESETS(AIEM), // FROMC=IBM-858,TOC=IBM-297 //* //* step 3 uses a utility to generate assembler language source //* from the output created in the previous two steps. The assembler //* language source is used as input to the ASMTRTS job stream in //* the install library to create a table useable by SecureZIP for //* zSeries. Please note that //* SecureZIP for z/OS relies on the DATA_DELIMITER and //* FILE_TERMINATOR characters. Anytime a non-standard table is //* used, it is the users' responsibility to ensure the correct //* values are specified for these processing options. Failure to //* do so may render the user data unuseable. //* //STEP3 EXEC PGM=BUILDTAB,PARM='EMAI' //STEPLIB DD DSN=PKWARE.MVS.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //TABIN DD DSN=USERID.TEST.CODESETS(EMAI),DISP=SHR // DD DSN=USERID.TEST.CODESETS(AIEM),DISP=SHR //TABOUT DD DSN=USERID.TEST.TRTABS(TRTEMAI),DISP=OLD
Notes:
The ICONV functions will make multiple code conversions if a direct translation from one codeset to another is not available. The interim codeset it uses is UCS2. Some installations disallow ICONV from using an interim code table via installation options and if that is the case it can be done manually by adding the additional steps.
376
Currently, double byte character sets are not supported by the BUILDTAB utility.
The specification of DATA_DELIMITER and FILE_TERMINATOR characters may be required depending on the character sets being used. The correct specification for those characters is critical for subsequent access to the data.
377
E FIPS-197 AES Certification of PKZIP and SecureZIP
The implementation of the AES algorithm used by PKZIP for MVS, Version 5.5 and higher (which includes SecureZIP for z/OS), has been validated in accordance with FIPS-197 for the Advanced Encryption Standard.
The NIST (National Institute of Standards and Technology), a branch of the US government and certified practitioners of the AES (Advanced Encryption Standard), has recognized PKWARE for demonstrating strong security competence in regards to the algorithm's strength and implementation within our products.
A list of AES implementations that NIST has validated as correctly implementing the AES algorithm can be found on the NIST Web site:
http://www.csrc.nist.gov/cryptval/aes/aesval.html
378
F Contact Information
PKWARE Web site: www.pkware.com
For licensing, contact Sales at 937-847-2374 (888-4PKWARE / 888-475-9273) or email [email protected].
For technical assistance, contact Technical Suppport:
937-847-2687
http://www.pkware.com/business_and_developers/support
PROBLEM REPORTING
Providing appropriate documentation on the initial call for a problem expedites the analysis and resolution process. The following sections describe the type of information that should be supplied for each category of problem.
General
When reporting a problem regarding PKZIPz, please be prepared to provide the following information:
The release level of the operating system PKZIPz is running under.
The release level of PKZIPz being run. This information can be found in the SYSPRINT output in message-ID ZPLI001I.
A description of the process being run and any differentiating circumstances from job(s) that do run.
A copy of the SYSPRINT output from a failing execution, with the command "-SHOW_SETTINGS" as the last command in the SYSIN.
Note: In ISPF, the SYSPRINT output can be found in a file immediately following the failure, the work file over-written with each new request, and can be found by selecting the following option from the main ISPF panel.
"S Sysprint Browse Log of last on-line execution"
A copy of the JOBLOG for a batch job execution.
379
If practical, please include the archive/Input File involved in the failing execution.
In the case of an Abend, a copy of the DUMP output from a failing execution with a //SYSABEND DD. This dump can be zipped (as TEXT) before transferring.
In the case of a LOOP/WAIT condition, cancel the run with a dump. Make sure the cancelled run contains a //SYSABEND DD. This dump can be zipped (as TEXT) before transferring.
When providing a SYSABEND DUMP, please remove any ABEND handlers such as ABEND AID or DUMP MASTER from the failing run.
ABEND AID can be circumvented by providing the "//ABNLIGNR DD DUMMY" JCL statement.
Output from a VIEWDETAIL before and after an update is performed.
If requested by Technical Support, SYSPRINT with various tracing options turned on.
Licensing When reporting a problem regarding LICENSING, please be prepared to provide the following information:
A copy of the JES output from the LICSHSYS job in INSTLIB.
A copy of the JES output from the LICPRINT job in INSTLIB.
If this is a build of a License, then supply a copy of the JES output from the License update job (LICUPDAT) being run.
If the problem occurs in a PKZIPz job then follow the steps outlined above.
ISPF When reporting a problem regarding ISPF, please be prepared to provide the following description of the problem to include:
The option selected
Any additional panel selections
The archive file type
A copy of the archive if an UNZIP or View operation is involved.
Description of results
Copy of the SYSPRINT of last operation (Option S)
Any error messages (screen capture/cut and paste as needed).
Release level of PKZIPz (is displayed in SYSPRINT).
A logical print of active allocations for the session.
From the command line of the SecureZIP panel involved, issue the command "TSO ISRDDN”
380
From the ISRDDN screen display "Current Data Set Allocations", issue the command "PRINTL"
Exit ISPF, when prompted select LIST data set options, Keep data set - New
Note the data set name that is kept and include its contents.
FTP SERVER requirements To upload abend dumps or printouts to PKWARE use the following JCL as an example:
//FTPSTEP EXEC PGM=FTP,PARM='BIGIRON.PKWARE.COM (EXIT' //SYSPRINT DD SYSOUT=* //INPUT DD * FTP_SUPPORT PKW!PKW CWD USUPPORT BINARY PUT 'YOUR.FULLY.QUALIFID.DSN' CLOSE QUIT //
381
Glossary
This glossary provides definitions for items that may have been referenced in the PKZIPz
documentation. It is not meant to be exhaustive. There are excellent source of documentation for computing terms on the Internet. For example:
IBM’s Terminology Web Site
http://www.networking.ibm.com/nsg/nsgmain.htm
Absolute Path Name
A string of characters that is used to refer to an object, starting at the highest level (or root) of the directory hierarchy. The absolute path name must begin with a slash (/), which indicates that the path begins at the root. This is in contrast to a Relative Path Name.
Access Method
A technique that is used to read a record from, or to write a record into, a file. Usually either: SAM (Sequential Access Method - where records are processed one after another in the order in which they appear in the file), or random (the individual records can be processed in any order) such as VSAM ).
AES
The Advanced Encryption Standard is the official US Government encryption standard for customer data.
Alternate Index
An index of a file based on a key different from the base. It allows the file to be processed in a secondary key order.
American Standard Code for Information Interchange (ASCII)
The ASCII code (American Standard Code for Information Interchange) was developed by the American National Standards Institute for information exchange among data processing systems, data communications systems, and associated equipment, and is the standard character set used on Windows and many UNIX-based operating systems. In a ZIP archive, ASCII is used as the normal character set for compressed text files. The ASCII character set consists of 7-bit control characters and symbolic characters, plus a single parity bit. Since ASCII is used by most microcomputers and printers,
382
text-only files can be transferred easily between different kinds of computers and operating systems. While ASCII code does include characters to indicate backspace, carriage return, etc., it does not include accents and special letters that are not used in English. To accomodate those special characters, Extended ASCII has additional characters (128-255). Only the first 128 characters in the ASCII character set are standard on all systems. Others may be different for a given language set. It may be necessary to create a different translation tables (see Translation Table) to create standard translation between ASCII and other character sets.
Application Programming Interface (API)
An interface between the operating system (or systems-related program) that allows an application program written in a high-level language to use specific data or services of the operating system or the program. The API also allows you to develop an application program written in a high-level language to access PKZIP data and/or functions of the PKZIP system.
Application System/400 (iSeries)
A family of general purpose computing systems from IBM which run Operating System/400 (OS/400).
Archive
(1) The act of transferring files from the computer into a long-term storage medium. Archived files are often compressed to save space.
(2) An individual file or group of files which must be extracted and decompressed in order to be used.
(3) A file stored on a computer network, which can be retrieved by a file transfer program (FTP) or other means.
(4) The PKZIP file that holds the compressed/zipped datafile.
Big ENDIAN
A binary (hexadecimal) representation of numeric data in which the most significant byte is on the left. In the context of bit flags, the most significant bit is on the left.
Binary File
A file that is to be handled in its native form without text translation.
Block
(1) A group of records that are recorded or processed as a unit.
(2) A set of adjacent records stored as a unit on a disk, diskette, or magnetic tape.
Cipher Block Chain (CBC)
Cipher Block Chaining refers to a method of encryption of blocks of data that involves
383
an initialization vector that is put together with the first block of data and the encryption key. This method of encryption makes sure that each block of data thereafter is uniquely modified, further protecting the data from fraudulent access.
Code Page
A specification of code points for each graphic character set or for a collection of graphic character sets. Within a given code page, a code point can have only one specific meaning. A code page is also sometimes known as a code set.
Configuration File
(1) A file that specifies the way a program functions.
(2) In PKZIP, the file that contains the default values needed for the system to run. These can usually be respecified to meet local user requirements. Several configuration files can be built and accessed via INCLUDE_CMD for certificate access, predefined command sequences, dataset selection lists and other processing settings.
Contingency Key
Key held for use under specific operational considerations or in support of specific contingency plans. (Source: National Information Assurance Glossary, revised May, 2003. Committee of National Security Systems (CNSS) Secretariat, National Security Agency)
Including a MASTER_RECIPIENT contingency key in a list of recipients when SecureZIP does strong encryption ensures that the organization that owns the key can decrypt the encrypted files.
CP Assist for Cryptographic Functions (CPACF)
A set of cryptographic instructions available on all central processors. These are available in varying degrees on zSeries z/890, z/990, and System z9 platforms.
Cryptographic Coprocessor Feature (CCF)
(1) A method of protecting data. Cryptographic services include data encryption and message authentication. This is available on systems supporting the G5/G6 chipsets, including MP2000, MP3000, 9672, as well as z-architecture systems z800 and z900.
Cryptography
(1) A method of protecting data. Cryptographic services include data encryption and message authentication.
(2) In cryptographic software, the transformation of data to conceal its meaning; secret code.
(3) The transformation of data to conceal its information content, to prevent its undetected modification, or to prevent its unauthorized use.
384
Cyclic Redundancy Check (CRC)
A Cyclic Redundancy Check is a number derived from a block of data, and stored or transmitted with the data in order to detect any errors in transmission. This can also be used to check the contents of a ZIP archive. It is similar in nature to a checksum. A CRC may be calculated by adding words or bytes of the data. Once the data arrives at the receiving computer, a calculation and comparison is made to the value originally transmitted. If the calculated values are different, a transmission error is indicated. The CRC information is called redundant because it adds no significant information to the transmission or archive itself. It is only used to check that the contents of a ZIP archive are correct. When a file is compressed, the CRC is calculated and a value is calculated based upon the contents and using a standard algorithm. The resulting value (32 bits in length) is the CRC that is stored with that compressed file. When the file is decompressed, the CRC is recalculated (again, based upon the extracted contents), and compared to the original CRC. Error results will be generated showing any file corruption that may have occurred.
Data Compression
The reduction in size (or space taken) of data volume on the media when performing a save or store operations.
Data Integrity
(1) The condition that exists as long as accidental or intentional destruction, alteration, or loss of data does not occur.
(2) Within the scope of a unit of work, either all changes to the database management systems are completed or none of them are. The set of change operations are considered an integral set.
Delimiter
A character or sequence of characters that marks the beginning or end of a unit of data. This is commonly used in non-record data streams in workstation and UNIX-based systems.
Dynamic Allocation (DYNALLOC)
Dynamic Allocation (DYNALLOC) is a facility utilizing the SVC99 function which allows a program to directly access a dataset without the need for corresponding JCL statements.
Encryption
The transformation of data into an unintelligible form so that the original data either cannot be obtained or can be obtained only by decryption.
Enqueue
The Enqueue macro (ENQ) is used to restrict access to a resource, so that only the appropriate number of users with the appropriate mode gain access to the resource at
385
one time. It is commonly used to "lock" a resource to prevent modifications from multiple sources to cancel out each other.
Extended Attribute
Information attached to an object that provides a detailed description about the object to an application system or user.
Extended Binary Coded Decimal Interchange Code (EBCDIC)
The Extended Binary Coded Decimal Interchange Code a coded character set of 256 8 bit characters. EBCDIC is similar in nature to ASCII code, which is used on many other computers. When ZIP programs compress a text file, they translate data from EBCDIC to ASCII characters within a ZIP archive using a translation table.
FIPS
Federal Information Processing Standards defining information processing standards for use within government agencies. Information regarding specific standards definitions are available online from the Computer Security Resource Center at csrc.nist.gov using keyword “FIPS”.
GDG
Generation Data Groups.
GZIP
GZIP (also known as GNU zip) is a compression utility designed to use a different standard for handling compressed file data in an archive.
ICF
Integrated Catalog Facility.
ICSF
ICSF is a software product that works with the hardware cryptographic feature and the z/OS Security Server (RACF element) to provide secure, high-speed cryptographic services in the z/OS environment. ICSF provides the application programming interfaces by which applications request the cryptographic services. The cryptographic coprocessor is secure, high-speed hardware that performs the actual cryptographic functions. The cryptographic feature available to your applications depends on the server or processor hardware.
IDCAMS
The utility program used by IBM’s Access Method Services to create and manage cataloged datasets.
386
Installation Verification Procedure (IVP)
A sample application, script, or jobstream provided to verify successful installation of a product (may be either software or hardware).
iSeries
AS400 Operating environments.
JCL
Job Control Language is a command language for mainframes and minicomputers, used for launching applications.
Job Entry Subsystem (JES)
An IBM licensed program that receives jobs into the system and processes all output data produced by the jobs. Commonly known as JES2 or JES3
Julian Date
A date format that contains the year in positions 1 and 2, and the day in positions 3 through 5. The day is represented as 1 through 366, right-adjusted, with zeros in the unused high-order positions. For example, the Julian date for April 6, 1987 is 87096.
Keyed Sequence
An order in which records are retrieved based on the contents of key fields in records. For example, a bank name and address file might be in order and keyed by the account number.
Keyword
A mnemonic (abbreviation) that identifies a parameter in a command.
LBI (Large Block Interface)
The set of BSAM, BPAM, and QSAM interfaces that deal with block sizes in 4 byte fields instead of 2 byte fields. This mode of operation is device- and system-dependent.
Lempel-Ziv (LZ)
A technique for compressing data. This technique replaces some character strings, which occur repeatedly within the data, with codes. The encoded character strings are then kept in a common dictionary, which is created as the data is being sent.
Little ENDIAN
A binary (hexadecimal) representation of numeric data in which the least significant byte is on the left. In the context of bit flags, the least significant bit is on the left.
387
MVS
Multiple Virtual Storage is the generic name for the portion of the OS/390 and z/OS operating systems which runs non Unix-System-Services workloads such as batch and TSO/E. It is in this environment that SecureZIP for z/OS executes.
NIST
National Institute of Standards and Technology is a part of the U.S. Department of Commerce, formerly called the National Bureau of Standards, that defines standards for voice, data, and video transmissions, encryption, and other kinds of technology.
Partitioned Dataset
A Partitioned Dataset (PDS) is a dataset in direct access storage that is divided into partitions (which are called members), each of which can contain a program, part of a program, JCL, parameters, or other forms of data. When a compression program is compressing a PDS, each member is treated as a separate file within the resultant ZIP archive. When an archive is decompressed to a PDS, each file within the archive creates a separate member within the PDS.
Path Name
(1) A string of characters used to refer to an object. The string can consist of one or more elements, each separated by a slash (/), and may begin with a slash. Each element is typically a directory or equivalent, except for the last element, which can be a directory or another object (such as a file).
(2) A sequence of directory names followed by a file name, each separated by a slash.
Program Temporary Fix (PTF)
A temporary solution to (or a bypass of) a problem that is necessary to provide a complete solution to correct a defect in a current unaltered release of a program. May also be used to provide an enhancement to a product before a new release of the product is available. Generally, PTFs are incorporated in a future release of the product.
RDW
Record Descriptor Word: Contains record length information as a prefix to the data
Record Format
A document or display that names each part of a file and provides specific information for each field such as length and type of information contained within the field.
Relative Path Name
A string of characters that is used to refer to an object, starting at some point in the directory hierarchy other than the root. A relative path name does not begin with a slash (/). The starting point is frequently a user's current directory. This is in contrast
388
to an Absolute Path Name and Path Name.
Return Code
A value generated by operating system software to a program to indicate the results of an operation by that program. The value may also be generated by the program and passed back to the operator.
Rijindael
The combined name of the two researchers that developed the Advanced Encryption Standard (AES) for the US Government (Dr. Joan Daemen and Dr. Vincent Rijmen).
Spanned Record
A logical record that stored across more than one block. This is commonly used to get around system limitations that blocks cannot be larger than x number of bytes. With spanned records, one record spans two or more blocks.
Translation Table
Translation tables are used by the PKZIP and PKUNZIP programs for translating characters in compressed text files between the ASCII character sets used within a ZIP archive and the EBCDIC character set used on IBM-based systems. These tables may be created and modified by you as documented in the user's guide.
Truncate
To cut off or delete the data that will not fit within a specified line width or display. This may also be attributed to data that does not fit within the specified length of a field definition.
Universal Time Coordinated (UTC)
A synonym for Greenwich Mean Time (GMT) which is the mean solar time of the meridian of Greenwich, England, and is the prime basis of standard time throughout the world.
Virtual Storage Access Method
The Virtual Sequential Access Method (VSAM) is an access method for the direct or sequential processing of fixed-length and variable-length records on direct access devices. The records in a VSAM dataset or file can be organized in logical sequence by a key field (key sequence dataset or KSDS), in the physical sequence in which they are written on the dataset or file (entry-sequence or PS), or by relative-record number (RR). The datasets are managed by the IDCAMS utility program and is used by commands and macros from within application programs.
ZIP Archive
A ZIP archive is used to refer to a single dataset that contains a number of files
389
compressed into a much smaller physical space by PKZIP software.
Index
&
&SYSUID, 126
3
3DES, 24
A
access method services, 43 ACTION, 127, 145 -ACTION(VIEWDETAIL), 49 actions, 53, 54 –ADD, 145 Advanced Options, 304 AES, 24 –ALIAS_NAME, 240 –ALIASMEMBER, 231 Allocation Units, 308 –ARCH, 286 –ARCHBLKSIZ, 149 –ARCHBUFSPACE, 263 –ARCHCATALOG, 263 –ARCHCISIZE, 264 –ARCHCISZ, 264 –ARCHDATACISIZE, 266 –ARCHDATACISZ, 266 –ARCHDATAEEXT, 266 –ARCHDATAFILE, 266 –ARCHDATANAME, 267 –ARCHDATANORD, 267 –ARCHDATANRUS, 282 –ARCHDATANWCK, 286 –ARCHDATAORD, 267 –ARCHDATAOWNER, 280 –ARCHDATAPRI, 267 –ARCHDATARUS, 282 –ARCHDATASEC, 268 –ARCHDATASHR, 282 –ARCHDATASPACE, 268 –ARCHDATAVOL, 268 –ARCHDCLASS, 154, 156, 159, 197, 201, 203, 222, 254 –ARCHDIRBLKS, 154 –ARCHEEXT, 270
–ARCHERASE, 269 –ARCHFILE, 270 –ARCHFOR, 270, 285 –ARCHFREECA, 271 –ARCHFREECI, 271 –ARCHIFILE, 157 –ARCHINDD, 157 –ARCHINFILE, 157 –ARCHIVE, 155 Archive Name, 303 ARCHIVE_BLKSIZE, 127, 149 ARCHIVE_COMMENT, 127, 153 ARCHIVE_DATACLASS, 127, 154, 156, 159, 197, 201,
203, 222, 254 ARCHIVE_DIR_BLOCKS, 127, 154 –ARCHIVE_DIRBLKS, 154 ARCHIVE_DSN, 127, 155 –ARCHIVE_DSNAME, 155 ARCHIVE_DSORG, 127, 156 ARCHIVE_FASTSEEK, 127 –ARCHIVE_IFILE, 157 –ARCHIVE_INDD, 157 ARCHIVE_INFILE, 127, 157 ARCHIVE_LRECL, 127, 157 ARCHIVE_MGMTCLASS, 128, 157 –ARCHIVE_MODEL, 279 –ARCHIVE_OFILE, 158 –ARCHIVE_OUTDD, 158 ARCHIVE_OUTFILE, 128, 158 ARCHIVE_RECFM, 128, 158 –ARCHIVE_RELEASE, 160 –ARCHIVE_RLSE, 160 ARCHIVE_SPACE_MULTIVOL, 128 ARCHIVE_SPACE_PRIMARY, 128, 159 –ARCHIVE_SPACE_RELEASE, 160 ARCHIVE_SPACE_RLSE, 128, 160 ARCHIVE_SPACE_SECONDARY, 128, 160 ARCHIVE_SPACE_TYPE, 128, 160 ARCHIVE_STORCLASS, 128, 161 ARCHIVE_TIMESTAMP, 128, 161 ARCHIVE_UNIT, 128, 162 ARCHIVE_VOLUMES, 128, 162 –ARCHLRL, 157 –ARCHMCLASS, 157
390
–ARCHMODEL, 279 –ARCHNOERASE, 269 –ARCHNONSPANNED, 284 –ARCHNOREUSE, 282 –ARCHNORLSE, 160 –ARCHNOWRITECHK, 286 –ARCHOFILE, 158 –ARCHOUTDD, 158 –ARCHOUTFILE, 158 –ARCHOWNER, 280 –ARCHPRIMARY, 159 –ARCHRECORDSIZE, 280 –ARCHREUSE, 282 –ARCHRLSE, 160 –ARCHSCLASS, 161 –ARCHSECONDARY, 160 –ARCHSHR, 282 –ARCHSPACE, 160 –ARCHSPANNED, 284 –ARCHTO, 285 –ARCHTYPE, 158 –ARCHUNIT, 162 –ARCHVOL, 162 –ARCHWRITECHK, 286 –ATTRCOMPAT, 163, 165 –ATTRIB, 237 –ATTRIB_COMPAT, 163, 165 ATTRIB_COMPATIBILITY, 128, 163, 165 –ATTRIBCENTRAL, 237 –ATTRIBLOCAL, 237 –ATTRIBUTE_COMPATIBILITY, 163, 165 AUTHCHK, 128, 166 authentication, 13, 16, 17, 19, 66
B
B, 307 –BINARY, 178 Binary Records, 107 Block Size, 308 Browse, 307 Browse Binary, 307 Browse Text, 307 –BUFFERSPACE, 263 –BUFSPACE, 263
C
–CACHEMEMORY, 175 CALLMODE, 128, 168 CANCEL, 301 –CATALOG, 263 Cataloged Dataset Name and INFILE Request Restrictions,
101 Cataloged Dataset Name Filter Requests, 98 certificate authority, 19, 65 certificate stores, 15, 21, 23, 62, 63, 64, 70 certificates, 13, 19, 20, 23, 61
root, 21 validation, 65 validity, 66
Changing Default Options, 302 –CHECK_SYSIN_MEMBER, 128, 168 –CISIZE, 264 –CNVEXT, 192 Code Page, 373 Command Details, 142 Command Icon Legend, 144 Command Syntax, 125 Compress and Store all of a User’s Files into Their Own
Archive, 55 Compressed by, 308 compressing a dataset, 47 Compressing a VSAM File, 116 Compressing Data from Tape, 120 Compressing Sequential Files, 111 Compression Method, 308 Compression Ratio, 308 COMPRESSION_LEVEL, 128, 169, 171 Configuration (Option ‘C’), 299 Configuration Manager, 56 Configuration Manager Development: Managing Control
Statements, 58 Contact PKWARE (Option ‘A’), 323 Control Statement Definitions, 58 control statements, 58 –COPY, 145 Copying a Tape-Based Archive to a Disk File, 119 Creation Date, 308 CRLF, 128, 171 cross platform compatibility, 10 Cyclic Redundancy Check, 8, 308
D
data base profile, 62 data compression, 7 Data Format - Binary Records, 107 Data Format - Text Records, 106 Data Formats - Text or Binary, 105 Data Set Filter, 303 Data Set Name, 302 DATA_DELIMITER, 129, 174 DATA_STORAGE, 129, 175 DATA_TRANS_API_ERRLIM, 176 DATA_TRANS_API_ERRLIM, 129 DATA_TRANS_API_ERROR, 177 DATA_TRANS_API_ERROR, 129 DATA_TRANS_API_LANGUAGE, 177 DATA_TRANS_API_LANGUAGE, 129 DATA_TRANS_API_NAME, 177 DATA_TRANS_API_NAME, 129 DATA_TRANS_API_PARM, 177 DATA_TRANS_API_PARM, 129 DATA_TRANS_API_TRACE, 178 DATA_TRANS_API_TRACE, 129 DATA_TRANS_API_WORKSIZE, 178 DATA_TRANS_API_WORKSIZE, 129 DATA_TYPE, 129, 178 Alias, 38 Dataset Aliases, 38
391
dataset name, 127, 142 DATATYPE_DETECT_DEPTH, 180 DATATYPE_DETECT_TABLE, 181 –DATATYPE_SCAN_DEPTH, 180 DATATYPE_TEXT_PERCENT, 181 Date/Time Zipped, 308 DD Statements, 114 DDNAME_PARMLIB, 129, 182 DDNAME_QZSORTIN, 129 DDNAME_QZSORTOUT, 129 DDNAME_SYSIN, 129, 182 DDNAME_SYSPRINT, 129, 182 DDNAME_ZPSORTIN, 183 DDNAME_ZPSORTOUT, 183 Debugging Controls, 59 Decompressing
sequential datasets, 50 decompressing a dataset, 50 decryption, 70, 78, 92 defaults, 56 Defaults (Options ZD and UD), 300 Defaults Files, 299 Defaults for –ZIPPED_DSN, 289 Defaults Module, 299 Delete, 307 –DELETE, 145 –DELIM, 174 DES, 23 –DETECT_DEPTH, 180 –DETECTX, 178 Determining File Size, 109 digital certificates. See certificates digital signing. See signing Directory Blocks, 308 DISP, 301 Display Fields, 307 Dsorg, 308
E
–E0, 169, 171 EBCDIC, 302 ECHO, 129, 183 EDCICONV, 373
Sample Job, 375 –EN, 169 ENCRYPT_CERT_LIMIT, 129, 184 encryption, 10, 12, 17, 26
algorithms, 12, 16, 23, 90 certificate-based, 14, 26, 62, 78 file name, 16, 74, 88 password, 12, 14, 26, 78 strong, 12
–ENCRYPTION_METHOD, 184 ENCRYTPION_METHOD, 130 Enhanced Tape Processing, 28, 164, 165 –ES, 169 –ESDS, 264 –EX, 169 Example
-VIEWDETAIL, 49 Example 1: Zip PDS to an Archive, 353 Example 2: Zip PDS to an Archive, 354 Example 3: Zip VSAM KSDS to an Archive, 355 Example 4: Summary View of a Dataset, 356 Example 5: Summary View of a Dataset, 357 Example 6: View with Detail of an Archive, 358 Example 7: Unzip an Archive to PDS, 360 Example 8: Unzip an Archive to PDS, 360 Example 9: Unzip an Archive to VSAM KSDS, 361 Examples
extracting data, 50 viewing archive contents, 48
–EXCLUDE(dsname mask), 130, 186 Exclusion Filter, 99 EXIT, 301 Extract, 307 –EXTRACT, 145 Extract with overwrite, 307 EXTRACT_PREVIEW, 130, 187 Extracting Data into a PDS, 114 Extracting Data into a VSAM File, 117 Extracting Data onto Tape, 121 Extracting Records into a Sequential File, 112
F
–FACILITY_ENCRYPTDATA, 187 –FACILITY_HASH, 189 –FACILITY_RANDOM, 190 –FAILONDUPKEYS, 269 File Attributes, 107, 121 File Concatenation for ZIP Processing, 113 File Considerations, 108 File Name, 308 File Name or File Mask, 113 File Selection Processing Notes, 100 File Selections vs. Commands, 126 File Support, 110 File Type, 308, 317 FILE_BUSY_WAITTIME, 130, 191 FILE_EXTENSION, 130, 192 FILE_TERMINATOR, 130, 198 filename encryption. See encryption FILENAME_API_ERRLIM, 193 FILENAME_API_ERRLIM, 130 FILENAME_API_ERROR, 193 FILENAME_API_ERROR, 130 FILENAME_API_LANGUAGE, 193 FILENAME_API_LANGUAGE, 130 FILENAME_API_NAME, 194 FILENAME_API_NAME, 130 FILENAME_API_PARM, 194 FILENAME_API_PARM, 130 FILENAME_API_TRACE, 194 FILENAME_API_TRACE, 130 FILENAME_API_WORKSIZE, 195 FILENAME_API_WORKSIZE, 130 FILENAME_ENCRYPTION, 130, 195 FILENAME_SELECT_CASE, 130
392
–FILEPROCERR, 216 –FILESELERR, 215 FIPS, 23 –FRESHEN, 145 –FTRAN, 257
G
–GDGALL, 199 GDGALL_SUPPORT, 130, 199 Getting Started with the ISPF Interface, 298 GZIP, 130, 199 GZIP Extensions, 296 GZIP Restrictions, 296 GZIP_SUFFIX, 131, 200 GZIPCRC_IGNORE, 131, 200
H
HIERARCHY, 131, 200 –HLQ, 258
I
IBM’s Terminology Web Site, 381 ICONV, 373 ICSF, 10, 187, 189, 190, 385 IEBGENER, 43 –IFILE, 208 –IGNOREDUPKEYS, 269 Implementation Notes for GZIP, 296 INCLUDE_CMD, 131 INCLUDE_SFX, 131 Including Changed Defaults, 302 –INDD, 208 INFILE, 131, 208 INFILE Requests, 99 –INFILE_DD, 208 Info, 307 Input ZIP Archive Files, 100 inputs, 57 INSERT_MEMBER, 131, 209 –INSERTMEMBER, 209 Integrated Cryptographic Service Facility. See ICSF International Code Page, 374 invoking services, 51 Invoking ZIP or UNZIP TSO command line interface, 52 ISPF panel interface, 56
J
JCL to run SECZIP, 46 JES2 SYSIN INFILE Support, 99 Job Card, 299
K
–KEY_PROTECT_LEVEL, 131, 209 –KEYPROTECT1, 209 keys, 17, 19, 25 –KSDS, –RRDS, 264
L
Large File Considerations, 108 Last-Referenced Date, 308 LDAP, 62, 63, 86 LDAP_ENCRYPT_CERT_SELECT, 131, 210 License Display (Option ‘L’), 322 LICENSE_HLQ, 131, 211 LICENSE_WTO_INFO, 131, 212 Line Commands, 306 –LMM, 213 LMOD_SUPPORT, 131, 211 LOAD, 301 Load Libraries, 115 Load Library, 299 Load Module Control, 115 LOCATE, 301 LOGGING_LEVEL, 131, 212 Lowest Acceptable RC, 299
M
Magnetic Tapes and Cartridges, 119 –MAKEESDS, 219 –MAKELIBRARY, 219 –MAKEPDS, 219 –MAKEPDSE, 219 –MAKESEQ, 219 –MAKEVSAM, 219 Managing a Sequential File ZIP Archive, 112 Managing a VSAM ZIP Archive, 119 Managing a ZIP Archive on Tape, 121 Managing ZIP Archives as PDS Members, 114 MASTER_RECIPIENT, 131, 213 –MEM_MDL, 213 –MEM_MODEL, 213 MEMORY_MODEL, 213 –MEMORY_MODEL, 131 Message, 308 Messages, 59 Messages (Option ‘M’), 321 –METHOD, 169 –MML, 213 –MMM, 213 –MMS, 213 More Files, 303, 317 MULTI_THREAD_LIMIT, 131, 214
N
Needed to Extract, 308 New ZIP Archive, 294 –NIASEP, 290 –NOA, 258 –NOALIAS_NAME, 240 NOALIASMEMBER, 231 NOAPI, 131 –NOARCHRLSE, 160 –NOATTRIB, 237 –NOCRLF, 171 –NODYNMSGS, 251
393
–NOECHO, 183 –NOGDGALL, 199 –NOGZIP, 199 –NOHIERARCHY, 200 –NOINSERTMEMBER, 209 Non-labeled Tapes (NL), 120 –NOOVERWRITE, 220 –NOPADVSAM, 226 –NOPATH, 228 –NORECALL, 231 –NORECURSE, 166, 184, 236, 249 NOSYSIN, 132, 215 –NOSYSIPT, 215 –NOTAPE, 242 Notes for –ZIPPED_DSN, 288 –NOVSAM, 261 Numeric, 302
O
Old ZIP Archive, 293 ON_FILE_ACCESS_ERROR, 132, 215 ON_FILE_IO_ERROR, 132, 216 Option ‘A’, 323 Option ‘C’, 299 Option ‘L’, 322 Option ‘M’, 321 Option ‘S’, 320 Option ‘U’, 316 Option ‘W’, 323 Option ‘Z’, 311 Option List, 302 options, 54 Options ZD and UD, 300 –OUT_DSORG, 219 –OUTASTR, 263 –OUTATTEMPTS, 262 –OUTATTR, 264 –OUTAUTH, 262 –OUTBLKSIZ, 217 –OUTBLKSIZE, 217 –OUTBUFSPACE, 263 –OUTCATALOG, 263 –OUTCISIZE, 264 –OUTCISZ, 264 –OUTCODE, 265 –OUTCONTROLPW, 265 –OUTDATAASTR, 263 –OUTDATAATT, 262 –OUTDATAAUTH, 262 –OUTDATACISIZE, 266 –OUTDATACISZ, 266 –OUTDATACODE, 265 –OUTDATACTLPW, 265 –OUTDATAEEXT, 266 –OUTDATAFILE, 266 –OUTDATAMRPW, 278 –OUTDATANAME, 267 –OUTDATANORD, 267 –OUTDATANRUS, 282
–OUTDATANWCK, 286 –OUTDATAORD, 267 –OUTDATAOWNER, 280 –OUTDATAPRI, 267 –OUTDATARDPW, 280 –OUTDATARUS, 282 –OUTDATASEC, 268 –OUTDATASHR, 282 –OUTDATASPACE, 268 –OUTDATAUPDPW, 285 –OUTDATAVOL, 268 –OUTDATAWCK, 286 –OUTDCLASS, 217 –OUTDIRBLKS, 218 –OUTDUPLICATES, 269 –OUTEEXT, 270 OUTFILE_BLKSIZE, 132, 217 OUTFILE_DATACLASS, 132, 217 OUTFILE_DD, 132, 218 OUTFILE_DIR_BLOCKS, 132, 218 –OUTFILE_DIRBLKS, 218 OUTFILE_DSNTYPE, 132, 219 –OUTFILE_DSORG, 219 OUTFILE_LRECL, 132, 220 OUTFILE_MGMTCLASS, 132, 220 OUTFILE_OVERWRITE, 132, 220 OUTFILE_PDS_ENQ, 132, 221 OUTFILE_RECFM, 132, 221 –OUTFILE_RELEASE, 223 –OUTFILE_RLSE, 223 OUTFILE_SPACE_MULTIVOL, 132 OUTFILE_SPACE_PRIMARY, 132, 223 –OUTFILE_SPACE_RELEASE, 223 OUTFILE_SPACE_RLSE, 132, 223 OUTFILE_SPACE_SECONDARY, 132, 223 OUTFILE_SPACE_TYPE, 132, 224 OUTFILE_STORCLASS, 132, 224 OUTFILE_UNIT, 132, 225 OUTFILE_VOLUMES, 133, 225 –OUTFOR, 285 –OUTFREECA, 271 –OUTIMBED, 271 –OUTINDXASTR, 272 –OUTINDXATT, 272 –OUTINDXAUTH, 272 –OUTINDXCISIZE, 273 –OUTINDXCISZ, 273 –OUTINDXCTLPW, 273 –OUTINDXEEXT, 274 –OUTINDXNAME, 275 –OUTINDXNORD, 275 –OUTINDXNRUS, 282 –OUTINDXORD, 275 –OUTINDXOWNER, 280 –OUTINDXPRI, 275 –OUTINDXRDPW, 276 –OUTINDXRUS, 282 –OUTINDXSEC, 276 –OUTINDXSHR, 282
394
–OUTINDXSPACE, 277 –OUTINDXUPDPW, 277 –OUTINDXVOL, 278 –OUTKEYS, 278 –OUTLRL, 220 –OUTMASTERPW, 278 –OUTMCLASS, 220 –OUTMODEL, 279 –OUTNOREPLICATE, 281 –OUTNOREUSE, 282 –OUTNORLSE, 223 –OUTNOWRITECHK, 286 –OUTOWNER, 280 –OUTPRIMARY, 223 –OUTREADPW, 280 –OUTRECOVERY, 281 –OUTREPLICATE, 281 –OUTREUSE, 282 –OUTRLSE, 223 –OUTSCLASS, 224 –OUTSECONDARY, 223 –OUTSHR, 282 –OUTSPACE, 224 –OUTSPEED, 281 –OUTTO, 285 –OUTTYPE, 221 –OUTUNIT, 225 –OUTUPDATEPW, 285 –OUTVOL, 225 –OUTWRITECHK, 286 –OVERWRITE, 220
P
–PAD, 225 PAD_CHAR, 133, 225 PAD_VSAM, 133, 226 –PADVSAM, 226 PARMLIB_DSNAME_UNZIP, 133, 226 PARMLIB_DSNAME_ZIP, 133, 226 PARMLIB_FILE_WAIT_MAX, 133, 227 PARMLIB_FILE_WAIT_TIMER, 133, 227 PartnerLink, 344, 347 –PASS, 228 PASSWORD, 133, 228 passwords, 26, 95 PATCH_REPORT, 133 –PATCH_REPORT, 145 PATH, 133, 228 PDS and PDSE Members, 113 –PDS_TARGET, 241 PEM, 23 PKCS#12, 23, 69 PKCS#7, 23, 65 PKI, 18, 19 PKNODUMP, 42 PKSPRINT, 42 PKSUPPRC, 133, 229 PKUNZIP, 103 –PRESERVE_CMD_SPACES, 133
–PREVIEW, 187 Preview Extract, 307 Primary Commands, 301, 305 Primary File Selection Inputs, 98 Primary Space, 308 private key, 16, 19, 20, 27, 73 PROCESS_ALIAS, 133, 231 Processing Entire Load Library, 115 Processing GDGs, 112 Processing GZIP Archives, 297 Processing Individual Members, 115 Processing Mode, 303 public key, 16, 19, 20 public-key, 62 –PWD, 228
Q
–Q, 212 –QUIET, 212
R
RC4, 25 –RDW, 238 –RECALL, 231 RECALL_TO_ZIP, 133, 231 RECIPIENT, 61, 133, 232 recipients, 16, 62, 63, 78
searching for, 86 recipients list, 84, 85 Record Format, 308 Record Size, 308 –RECURSE, 166, 184, 236, 249 RECURSE_LEVELS, 133, 236, 239 region size and storage usage, 39 reserved DDNAMEs, 41 RESET, 301 restrictions, 37 return codes, 47
S
SAVE, 301 SAVE_FILE_ATTRIBUTES, 134, 237 SAVE_LRECL, 134, 238 Secondary Space, 308 SECUNZIP, 46, 65, 103
Invoking under TSO, 51 Invoking using JCL, 46, 51
SecureZIP Partner, 344 SECUREZIP_CONFIG, 134, 149, 240 SECZIP, 46, 65, 103
Invoking under TSO, 51 Invoking using JCL, 46, 51
SELECT_CATALOGED_ALIAS, 134, 240 –SELECT_DSN_ALIAS, 240 SELECT_FROM_PDS, 134, 241 –SELECT_GDGALL, 199 –SELECT_MIGRATED, 231 SELECT_TAPE, 134, 242 –SELECT_VSAM, 261
395
Selecting PDS Members for Compression, 113 Sequential Files, 111 SET_ERROR_RC, 134, 242 Setting VIEW Options, 303, 309, 313, 314, 315, 316, 318,
319, 320 SHOW_SETTINGS, 134, 242 SIGN_ARCHIVE, 134, 243 SIGN_FILES, 134, 246 SIGN_HASHALG, 134, 248 SIGNAL_ZIP64, 134, 249 signing, 13, 16, 19, 20
archives, 16 SIMULATE, 134, 249 Simulation Mode, 317 smart cards, 13 –SMM, 213 SNAP_SYSOUT_CLASS, 134, 250 SORT, 42 Sort Field, 303 Sort Order, 303 Sort Output, 303 sponsor, 344 Sponsor Distribution Package, 345 –SS, 242 STAGE_TAPE_ON_DISK, 134, 250 –STAGE_TAPE_TO_DISK, 250 –STRIP, 250 STRIP_CHAR, 134, 250 Summary of Available Commands, 126 Summary of Commands Affecting ZIP Filename, 102 Summary View of a Dataset, 356, 357 SUPPRESS_DYNALLOC_MSGS, 134, 251 SYSPRINT, 42 Sysprint Allocation, 299 SYSPRINT Browse (Option ‘S’), 320 SYSPRINT_DCB, 251 –SYSPRINT_DCB, 134 SYSPRINT_SYSOUT_CLASS, 135, 252 system utilities, 42
T
–TASKS, 214 TEMP_BLKSIZE, 135, 252 TEMP_DATACLASS, 135, 253 TEMP_MGMTCLASS, 135, 253 TEMP_RECFM, 135, 253 TEMP_SPACE_MULTIVOL, 135 TEMP_SPACE_PRIMARY, 135, 254 TEMP_SPACE_SECONDARY, 135, 254 TEMP_SPACE_TYPE, 135, 255 TEMP_STORCLASS, 135, 255 TEMP_UNIT, 135, 255 TEMP_VOLUMES, 135, 256 –TEMPBLKSIZ, 252 –TEMPDCLASS, 253 Temporary Dataset, 293 –TEMPPRI, 254 –TEMPPRIMARY, 254 –TEMPSCLASS, 255
–TEMPSEC, 254 –TEMPSECONDARY, 254 –TEMPSPACE, 255 –TEMPTYPE, 253 –TEMPUNIT, 255 –TERM, 198 –TEST, 145 Text, 302 –TEXT, 178 Text Records, 106 –TIMESTAMP, 161 To Compress Data into a ZIP Archive on Tape, 122 To Create a New VSAM File, 118 To Extract Data from a Tape-Based Archive, 123 To Overwrite a current VSAM File, 118 To Process “Sparse” RRDS Files, 119 To Process Multiple-Volume Tape Archives, 122 To Restore a Compressed VSAM File, 118 To Update a VSAM ESDS ZIP Archive, 119 To Update Files in a Tape-Based Archive, 124 To View a Tape-Based Archive, 123 TRACE_TABLE_SIZE, 135, 256 –TRAN, 256 Translate table, 373 TRANSLATE_TABLE_DATA, 135, 256 TRANSLATE_TABLE_FILEINFO, 135, 257 TRANSLATION_MODE, 135 Triple DES, 24 Troubleshooting, 59 TRTEBAA, 257, 374 TRTEBAI, 257, 374 TRTEEAA, 257, 374 TRTEEAI, 257, 374 TRTEFAA, 257, 374 TRTEFAI, 257, 374 TRTEGAA, 257, 374 TRTEGAI, 257, 374 TRTEIAA, 257, 374 TRTEIAI, 257, 374 TRTEJAA, 257, 374 TRTEJAI, 257, 374 TRTEMAA, 257, 374 TRTEMAI, 257, 374 TSO Prefix, 299
U
Unsupported File Types, 119 UNZIP (Option ‘U’), 316 Unzip an Archive to PDS, 360 Unzip an Archive to VSAM KSDS, 361 –UNZIPCONFI, 226 Unzipped Size, 308 UNZIPPED_DSN, 135, 258 –UNZIPPED_DSNAME, 258 –UPDATE, 145 updating or refreshing a file, 51 USE_FILE_ATTRIBUTES, 237 –USE_SAVED_LRECL, 238 user input sources (MVS), 58
396
V
–VERBOSE, 212 View, 307 –VIEW, 145 View Archive (Option ‘V’), 302 View Binary, 307 View Text, 307 View Type, 303 View with Detail of an Archive, 358 –VIEWDETAIL Display, 121 VIEWDETAIL of a KSDS in an Archive, 116 viewing the contents of an archive, 48 Volume, 308 Volume List, 302 VSAM, 135, 261 VSAM Clusters for –ZIPPED_DSN, 289, 290 VSAM Files, 115 VSAM_ACCOUNT, 135, 262 VSAM_ATTEMPTS, 136, 262 VSAM_AUTH_EP, 136, 262 VSAM_AUTH_STRING, 136, 263 VSAM_BUFFERSPACE, 136, 263 VSAM_CATALOG, 136, 263 VSAM_CISIZE, 136, 264 VSAM_CLUSTER_TYPE, 136, 264 VSAM_CODE, 136, 265 VSAM_CONTROLPW, 136, 265 VSAM_DATA_CISIZE, 136, 266 VSAM_DATA_EXCEPTIONEXIT, 137, 266 VSAM_DATA_FILE, 137, 266 VSAM_DATA_NAME, 137, 267 VSAM_DATA_ORDERED, 137, 267 VSAM_DATA_PRIMARY, 137, 267 VSAM_DATA_SECONDARY, 137, 268 VSAM_DATA_SPACE_TYPE, 137, 268 VSAM_DATA_VOLUMES, 137, 268 VSAM_DATACLASS, 137, 269 VSAM_DUPLICATE_ERROR, 137, 269 VSAM_ERASE, 137, 269 VSAM_EXCEPTIONEXIT, 138, 270 VSAM_FILE, 138, 270 VSAM_FOR, 138, 270 VSAM_FREESPACE_CA, 138, 271 VSAM_FREESPACE_CI, 138, 271 VSAM_IMBED, 138, 271 VSAM_INDEX_ATTEMPTS, 138, 272 VSAM_INDEX_AUTH_EP, 138, 272 VSAM_INDEX_AUTH_STRING, 138, 272 VSAM_INDEX_CISIZE, 138, 273 VSAM_INDEX_CODE, 138, 273 VSAM_INDEX_CONTROLPW, 139, 273 VSAM_INDEX_EXCEPTIONEXIT, 139, 274 VSAM_INDEX_FILE, 139, 274 VSAM_INDEX_MASTERPW, 139, 274 VSAM_INDEX_NAME, 139, 275 VSAM_INDEX_ORDERED, 139, 275 VSAM_INDEX_PRIMARY, 139, 275 VSAM_INDEX_READPW, 139, 276 VSAM_INDEX_SECONDARY, 139, 276
VSAM_INDEX_SPACE_TYPE, 139, 277 VSAM_INDEX_UPDATEPW, 140, 277 VSAM_INDEX_VOLUMES, 140, 278 VSAM_KEYS, 140, 278 VSAM_MASTERPW, 140, 278 VSAM_MGMTCLASS, 140, 279 VSAM_MODEL, 140, 279 VSAM_ORDERED, 140, 279 VSAM_OWNER, 140, 280 VSAM_READPW, 140, 280 VSAM_RECORDSIZE, 140, 280 VSAM_RECOVERY_OPT, 140, 281 VSAM_REPLICATE, 140, 281 VSAM_REUSE, 141, 282 VSAM_SHAREOPTIONS, 141, 282 –VSAM_SHROPT, 282 –VSAM_SHROPTS, 282 VSAM_SPACE_PRIMARY, 141, 282 VSAM_SPACE_SECONDARY, 141, 283 VSAM_SPACE_TYPE, 141, 283 VSAM_SPANNED, 141, 284 VSAM_STORCLASS, 141, 284 VSAM_TO, 141, 285 –VSAM_TYPE, 264 VSAM_UPDATEPW, 141, 285 –VSAM_VOLUMES, 268 VSAM_WRITECHECK, 141, 286 –VSAMCISIZE, 264 –VSAMCISZ, 264 –VSAMESDS, 264 –VSAMKSDS, 264 –VSAMRRDS, 264 –VSAMTYPE, 264
W
What is GZIP?, 295 What’s New (Option ‘W’), 323 Why use GZIP?, 295
X
X.509, 20, 65 XTAPE, 122, 163, 164
Y
Y/N, 302
Z
–ZDW, 238 Zip (Option ‘Z’), 311 ZIP archive
viewing contents, 48 ZIP archives, 7 ZIP File Names, 102 Zip PDS to an Archive, 353, 354 ZIP Processing File Selection, 98 Zip VSAM KSDS to an Archive, 355 ZIP_UNMOVABLE_CHKPT, 286 –ZIPCONFIG, 226 –ZIPCUR, 241
397
ZIPPARM Copy Member, 335, 337, 338, 339 Zipped Size, 308
ZIPPED_DSN, 141, 287 ZIPPED_DSN_SEPARATOR, 141, 290