IBM. User's Guide. SMP/E for z/os SA

Transcription

1 SMP/E for z/os IBM User's Guide SA

2 Note Before using this information and the product it supports, read the information in Notices on page 241. This edition applies to IBM SMP/E for z/os, V3R6 (program number 5655-G44) and to all subsequent releases and modifications until otherwise indicated in new editions. Last updated: January 8, 2019 Copyright IBM Corporation 1986, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents Figures ix Tables xi About this document xiii Who should read this publication xiii SMP/E publications xiii How to send your comments to IBM.. xv If you have a technical problem xv Summary of changes xvii Changes made in SMP/E Version 3 Release 6.. xvii Changes made in SMP/E Version 3 Release 5.. xvii Changes made in SMP/E Version 3 Release 4 xviii Chapter 1. SMP/E primer What is SMP/E, and why should I use it? Understanding your system Changing the elements of the system Keeping track of the elements of the system... 7 How does SMP/E work? The distribution and target libraries The consolidated software inventory (CSI) What are the basic SMP/E commands I need to know? Setting the zone you want to work on Receiving the SYSMOD into SMP/E's data sets 13 Applying the SYSMOD to the target libraries.. 13 Restoring the target libraries to the previous level 13 Accepting the SYSMOD and updating the distribution libraries Displaying SMP/E data Flow of SMP/E SYSMOD processing Receiving the SYSMOD into SMP/E's data sets.. 14 What happens during RECEIVE processing What happens during internet service retrieval 15 How SMP/E keeps track of RECEIVE processing 16 Using the RECEIVE command Summary of the RECEIVE command Applying the SYSMOD to the target libraries What happens during APPLY processing How SMP/E keeps track of APPLY processing. 20 Using the APPLY command Summary Restoring the target libraries to the previous level 23 What happens during RESTORE processing.. 24 How SMP/E keeps track of RESTORE processing 24 Using the RESTORE command Summary Accepting the SYSMOD into the distribution libraries What happens during ACCEPT processing How SMP/E keeps track of ACCEPT processing 28 Using the ACCEPT command Summary Displaying SMP/E data Using the query dialogs Using the LIST command Using the REPORT commands SMP/E CSI application programming interface 35 Summary Chapter 2. SMP/E concepts What is SMP/E? What are SYSMODs? Data sets used by SMP/E How SMP/E can help you install and maintain products Where to begin Installing SYSMODs Monitoring your system Managing the SMP/E database Managing zones Linking and relinking modules General SMP/E processing Chapter 3. Preparing to use SMP/E.. 49 Authorizing use of SMP/E commands and services 49 Allocating and initializing data sets in the SMP/E database CSI data sets PTS data sets SCDS data sets How to dynamically allocate data sets to be used during SMP/E processing Sources of information for dynamic allocation.. 65 How dynamic allocation works Defining utility programs and associated parameters to SMP/E Using default values for utility programs Defining values for utility programs Example: How to request the desired utility processing Recovering after errors from utility processing Overview of your input to retry processing Example: How to request the desired retry processing Connecting SMP/E dialogs to ISPF Check for required programs Add dialog modules to the PCF command table 73 Concatenate the dialog libraries Connect the dialogs to ISPF Customize the SMP/E dialogs Setting up SMP/E for easier operation Recommended values for OPTIONS entry Recommended DDDEF entries for link-edit utility output Copyright IBM Corp. 1986, 2017 iii

4 Specifying automatic cross-zone requisite checking Defining the information needed to invoke SMP/E 82 Required JCL statements Sample cataloged procedure for SMP/E Checking that you have the appropriate access.. 88 Defining exit routines Chapter 4. Preparing to use Internet service retrieval Identity and authentication overview Obtaining a user certificate Uploading the user certificate to z/os Setting up z/os security server RACF Access to the RACDCERT command Creating key rings Enabling certificate authority certificates Adding certificate authority certificates Adding the user certificate to your RACF data base Connecting the certificates to the key ring Sharing a user certificate among multiple user IDs Debugging key ring and certificate issues Replacing a user certificate that expired Refreshing RACF classes Setting up alternate security products Defining the ORDERSERVER input for RECEIVE ORDER Defining the CLIENT input for RECEIVE ORDER 98 Options that affect Java Options that affect HTTPS operations Options that affect download operations Network configuration notes Summary Example Chapter 5. Preparing for secure Internet delivery Secure Sockets Layer overview Enabling certificate authority certificates Access to certificate authority certificates Displaying certificate authority certificates Adding certificate authority certificates Access for SMP/E to use certificate authority certificates Refreshing RACF classes Define CLIENT input for RECEIVE and GIMGTPKG Options that affect HTTPS operations Options that affect FTPS operations Example Chapter 6. Installing a new function 117 Introduction RECEIVE-APPLY-ACCEPT method The standard RECEIVE-APPLY-ACCEPT method 118 Preparing your system Staging the SYSMODs: The RECEIVE process 119 Updating the target libraries: The APPLY process Testing the new function Updating the distribution libraries: The ACCEPT process Checking other zones for requisites: REPORT CROSSZONE Chapter 7. Installing preventive service Introduction CBPDO tapes ESO tapes A RECEIVE ORDER request Preventive service process: Summary Preparing your system Staging the SYSMODs: The RECEIVE process Updating the target libraries: The APPLY process 129 Checking the update (APPLY CHECK) Updating the target library (APPLY) Installing PTFs that need special processing Testing the new service level Updating the distribution libraries: The ACCEPT process Checking the update (ACCEPT CHECK) Updating the distribution library (ACCEPT) Installing PTFs that need special processing Chapter 8. Installing corrective service 139 Introduction Building or checking the fix Preparing your system Staging the SYSMODs: the RECEIVE process Generating a service request using the RECEIVE ORDER Command Updating the target libraries: the APPLY process 142 Checking the update (APPLY CHECK) Updating the target library (APPLY) Testing the corrective service Updating the distribution libraries: the ACCEPT process Checking the update (ACCEPT CHECK) Updating the distribution library (ACCEPT) Chapter 9. Installing a user modification Introduction Preparing your system Staging the SYSMODs: The RECEIVE process Updating the target libraries: The APPLY process 148 Checking the update (APPLY CHECK) Updating the target library (APPLY) Testing the USERMOD Updating the distribution libraries: The ACCEPT process Chapter 10. Managing exception SYSMODs Introduction iv SMP/E V3R6.0 for z/os V2R3 User's Guide

5 What SMP/E does with the HOLDDATA Initial entry into staging data sets: RECEIVE 152 Updating target libraries: APPLY Updating distribution libraries: ACCEPT Removing HOLDDATA from SMP/E data sets 154 Sources of HOLDDATA CBPDO tapes ESO tapes PSP information Automated service delivery package How to process HOLDDATA Chapter 11. Creating cross-product, cross-zone load modules: The LINK MODULE command When to use LINK MODULE How to use LINK MODULE Chapter 12. Displaying the data managed by SMP/E: The LIST command Introduction Listing all the SMP/E data Listing by specific entry type Listing specific entries Listing by FMID or FMIDSET Listing to compare two zones Summary Chapter 13. Changing the data SMP/E manages: The UCLIN command Introduction When to use UCLIN How to use UCLIN Chapter 14. Identifying cross-zone requisites: The REPORT CROSSZONE command Introduction Identifying zones to be processed Running the REPORT CROSSZONE command Installing the SYSMODs Chapter 15. Identifying installed SYSMODs affected by error holds: The REPORT ERRSYSMODS command Introduction Running the REPORT ERRSYSMODS command 179 Installing the SYSMODs Chapter 16. Listing the source IDs in a zone: The REPORT SOURCEID command Introduction Running the REPORT SOURCEID command Listing the SYSMODs Chapter 17. Comparing the SYSMODs installed in two zones: The REPORT SYSMODS command Introduction Running the REPORT SYSMODS command Installing the SYSMODs Chapter 18. Building a user modification Choosing between a USERMOD and a function SYSMOD Creating the MCSs The ++USERMOD MCS The ++VER MCS The ++JCLIN MCS MOD and ++ZAP MCSs MAC and ++MACUPD MCSs SRC and ++SRCUPD MCSs The ++PROGRAM MCS Data element MCSs Hierarchical file system element MCSs Examples of USERMODs Example 1: Updating a module Example 2: Replacing a module Example 3: Adding new modules Example 4: Replacing a macro or source code 192 Example 5: Updating a macro or source code 193 Example 6: Adding new source code Example 7: Adding new source code that uses an IBM-supplied macro Example 8: Adding a new module that uses an IBM-Supplied macro Chapter 19. Determining which SYSMODs led others to fail: The causer SYSMOD summary report Introduction Using causer SYSMOD information Resolving errors for all SYSMODs that failed 199 Resolving errors for a single SYSMOD that failed Example Chapter 20. Java archive update exploiter's guide JAR replacements in FMIDs JAR updates in PTFs JAR replacements in PTFs Appendix A. Migration Migration overview Terms you need to know SMP/E release levels Developing a migration strategy SMP/E V3R6 overview Multitasking using GIMDDALC SYSPRINT allocation Adding SAF checks to SMP/E processing (IO11698) Contents v

6 Cross Global Zone Reporting SYSMOD Comparison HOLDDATA Report Retention of HOLDDATA (IO13643) SMP/E V3R5 overview Enhanced utility input Long SOURCEID support ZONEMERGE command HTTPS and FTP enhancements HOLDDATA report changes BYPASS(HOLDSYS) message severity changes 212 ZONEEDIT enhancement RECEIVE ORDER processing enhancements Programmatic PSP-bucket processing SMP/E V3R4 overview Enhancement to the RECEIVE command Impacts to SMP/E zone entries ICSF not required for GIMZIP and RECEIVE FROMNETWORK Improved load module build processing SMP/E order management dialog SMP/E query dialog SMP/E V3R3 overview GIMGTPKG service routine Enhancements to GIMZIP and GIMUNZIP service routines RECEIVE FROMNETWORK FTP interface enhancements REJECT CHECK command Extended RECEIVE SOURCEID processing SPCLCMOD and CMWA SMP/E V3R2 overview LINK LMODS command REPORT CALLLIBS command removal UPGRADE command GIMXSID service routine GIMZIP: Archive segmentation GIMZIP: User defined subdirectories Java archive files Smaller SMPLTS data set DUMMY data set for SYSDEFSD SMP/E dialog customization GIMUTTBL removal SMP/E V3R1 overview Defining exit routines using SMPPARM member GIMEXITS Dynamic allocation using SMPPARM member GIMDDALC Enhanced link name values Removal of function to create backup IEANUC01 load modules Conditional JCLIN processing Network delivery of SMP/E input AMODE=64 and COMPAT=PM4 link edit parameters Selected SMP/E data sets may now reside in a UNIX file system HFS data set identification SMPPTS spill data sets HOLDDATA summary reports SMP/E load modules and service routines moved to SYS1.MIGLIB GIMXTRX service routine OS/390 version 2 release 7 SMP/E overview SMP/E planning and migration assistant Data element reformatting Description for a SYSMOD Improved protection for UNIX file system files 226 Pre-built load module support Product data Sequential data set support Shell script support Symbolic link support OS/390 version 2 release 5 SMP/E overview CBIPO dialogs Client code installation Global zone merge Library change interface Improved load module build processing Load module return code Performance improvements PTF compaction in SMPPTS data set Enhanced RECEIVE command processing Reduced SMP/E message output GIMAPI: All entries and subentries support GIMAPI: Version support OS/390 version 1 release 3 SMP/E overview API for user access to the CSI Enhanced cross-zone requisite checking Enhanced exception SYSMOD report Enhanced ++IF FMID processing Enhanced internal HOLD SYS processing Enhanced ZONEEDIT command Enhancements to the binder utility in DFSMS/MVS System/390 service update facility OS/390 version 1 release 2 SMP/E overview BLOCKSIZE=8800 for SMP/E data sets BUILDMCS command Bypassing system holds for specific SYSMODs 232 FMIDSET selection Receiving relative file data sets created from PDSEs SMP/E dialogs: FIND command SMP/E GIMOPCDE member moved from PARMLIB Appendix B. Recommended service upgrade (RSU) Appendix C. Accessibility Accessibility features Consult assistive technologies Keyboard navigation of the user interface Dotted decimal syntax diagrams Notices Terms and conditions for product documentation 243 IBM Online Privacy Statement Policy for unsupported hardware Minimum supported hardware Trademarks vi SMP/E V3R6.0 for z/os V2R3 User's Guide

7 Glossary Index Contents vii

8 viii SMP/E V3R6.0 for z/os V2R3 User's Guide

9 Figures 1. Creating load modules Introducing an element Preventing problems with an element Fixing problems with an element Customizing an element PTF replacement PTF prerequisite Load module constructions The public library The distribution and target libraries z/os system with SMP/E Flow of SMP/E SYSMOD processing Results of RECEIVE processing Results of APPLY processing Results of RESTORE processing Results of ACCEPT processing Query selection menu CSI query panel CSI query - Select entry panel CSI query - SYSMOD entry panel Example of a SYSMOD hierarchy Summary of zone relationships A single-csi structure A multiple-csi structure Using a separate global zone for each subsystem Using one CSI for the whole system Using a master CSI Using a master CSI and a separate CSI for each zone Using a master CSI and one CSI per SREL Relationships between zone definition entries Relationships of OPTIONS, UTILITY, zone definition entries and the SET command Sample logon procedure that concatenates SMP/E and ISPF libraries Sample SMP/E cataloged procedure APPLY SYSLIB concatenation: APPLY different from ACCEPT ACCEPT SYSLIB concatenation: APPLY different from ACCEPT SYSMOD Status Report: Sample Report for APPLY Causer SYSMOD summary report: sample report for APPLY Copyright IBM Corp. 1986, 2017 ix

10 x SMP/E V3R6.0 for z/os V2R3 User's Guide

11 Tables 1. Publications for IBM SMP/E for z/os, V3R6 xiii 2. Functions and resource names that must be carefully controlled Entries controlling SMP/E processing Entries describing the status and structure of the target and distribution libraries Default values for UTILITY entries How to request the utility processing How to request the retry processing ISPF libraries and related SMP/E target libraries SMPTABL data set allocations Sources for functions and their installation information Format of a CBPDO tape Format of an ESO CBPDO/service level/psp HOLDDATA example Alternatives to UCLIN Comparison of USERMODs and function SYSMODs Information needed to add new source code 193 Copyright IBM Corp. 1986, 2017 xi

12 xii SMP/E V3R6.0 for z/os V2R3 User's Guide

13 About this document This publication documents a new and enhanced version of SMP/E. New or changed information is identified by revision bars ( ) to the left of the addition or change. Who should read this publication SMP/E publications Anyone who uses SMP/E, or who wants to understand SMP/E processes, should read this publication. After reading this publication, you should be able to do most SMP/E processes. You may have to refer to SMP/E for z/os Commands for details on commands. The IBM SMP/E for z/os, V3R6 publications are available as PDF files in the z/os Internet library ( zosinternetlibrary). Table 1 lists the IBM SMP/E for z/os, V3R6 publications and briefly describes each one. For information about z/os publications and more information about the IBM SMP/E for z/os, V3R6 books, see z/os Information Roadmap. Table 1. Publications for IBM SMP/E for z/os, V3R6 Title SMP/E for z/os Messages, Codes, and Diagnosis, GA SMP/E for z/os Commands, SA SMP/E for z/os Reference, SA SMP/E for z/os User's Guide, SA Description Explains SMP/E messages and return codes and the actions to take for each; and how to handle suspected SMP/E problems. Explains SMP/E commands and processing in detail. Explains SMP/E modification control statements, data sets, exit routines, and programming interfaces in detail and provides additional SMP/E reference material. Describes how to use SMP/E to install programs and service. Copyright IBM Corp. 1986, 2017 xiii

14 SMP/E publications xiv SMP/E V3R6.0 for z/os V2R3 User's Guide

15 How to send your comments to IBM We invite you to submit comments about the z/os product documentation. Your valuable feedback helps to ensure accurate and high-quality information. Important: If your comment regards a technical question or problem, see instead If you have a technical problem. Submit your feedback by using the appropriate method for your type of comment or question: Feedback on z/os function If your comment or question is about z/os itself, submit a request through the IBM RFE Community ( Feedback on IBM Knowledge Center function If your comment or question is about the IBM Knowledge Center functionality, for example search capabilities or how to arrange the browser view, send a detailed to IBM Knowledge Center Support at ibmkc@us.ibm.com. Feedback on the z/os product documentation and content If your comment is about the information that is provided in the z/os product documentation library, send a detailed to mhvrcfs@us.ibm.com. We welcome any feedback that you have, including comments on the clarity, accuracy, or completeness of the information. To help us better process your submission, include the following information: v Your name, company/university/institution name, and address v The following deliverable title and order number: SMP/E User's Guide, SA v The section title of the specific information to which your comment relates v The text of your comment. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute the comments in any way appropriate without incurring any obligation to you. IBM or any other organizations use the personal information that you supply to contact you only about the issues that you submit. If you have a technical problem If you have a technical problem or question, do not use the feedback methods that are provided for sending documentation comments. Instead, take one or more of the following actions: v Go to the IBM Support Portal (support.ibm.com). v Contact your IBM service representative. v Call IBM technical support. Copyright IBM Corp. 1986, 2017 xv

16 xvi SMP/E V3R6.0 for z/os V2R3 User's Guide

17 Summary of changes This document contains terminology, maintenance, and editorial changes to improve consistency and retrievability. Technical changes or additions to the text and illustrations are indicated by a vertical line to the left of the change. Changes made in SMP/E Version 3 Release 6 This document contains information that was previously presented in SMP/E User's Guide, SA , which supports SMP/E Version 3 Release 5. For SA Changes were made to the "Recommended service upgrade" appendix, see Appendix B, Recommended service upgrade (RSU), on page 235. A change was made to the download servers to use certificates signed by DigiCert Global Root CA, see Chapter 5, Preparing for secure Internet delivery, on page 107 for more information. Changes were made to the CA certificates that the IBM Automated Delivery Request server (the "HSB") can use; for more information, see Chapter 4, Preparing to use Internet service retrieval, on page 91 and Chapter 5, Preparing for secure Internet delivery, on page 107. Support for HTTPS downloads was added; see Chapter 5, Preparing for secure Internet delivery, on page 107. Changes made in SMP/E Version 3 Release 5 For SA New information: v Authorizing use of SMP/E commands and services on page 49. This change is available via APAR I v The "Readers' Comments - We'd Like to Hear from You" section at the back of this publication has been replaced with a new section How to send your comments to IBM on page xv. The hardcopy mail-in form has been replaced with a page that provides information appropriate for submitting readers comments to IBM. Changed information: v Figure 33 on page 86 For SA New information: v Checking that you have the appropriate access on page 88 SA New information: Copyright IBM Corp. 1986, 2017 xvii

18 v SMP/E V3R5 overview on page 210 v In the glossary, the definition of the SMPHRPT data set was added. v A description of the COMPAT parameter was added to EXEC statement on page 83. v A note about the STEPLIB DD statement was added to DD statements on page 84. Changed information: v In the glossary, the description of the SMPOUT data set was updated to include the SMPHRPT data set. Deleted information: v The summary of interface changes section was removed. Changes made in SMP/E Version 3 Release 4 For SA Changed information: v A description of the <FTPOPTIONS> tag was added to Options that affect download operations on page 100. v Refreshing RACF classes on page 97 was updated to include the new <FTPOPTIONS> tag. v The example in Defining the CLIENT input for RECEIVE ORDER on page 98 was updated to include the new <FTPOPTIONS> tag. For SA New information: v etrust CA-Top Secret security for z/os users on page 97 v Debugging key ring and certificate issues on page 96 For SA New information: v Replacing a user certificate that expired on page 96 Changed information: v The "ORDER RETENTION Subentry on the OPTIONS Entry" information in Appendix A, Migration, on page 207 was updated. For SA Changed information: v Chapter 4, Preparing to use Internet service retrieval, on page 91 was rewritten to support APAR IO Information was added and some topics were moved within the chapter. For SA Changed information: v The last portion of the topic Options that affect Java on page 98 was updated. xviii SMP/E V3R6.0 for z/os V2R3 User's Guide

19 For SA New information: v Refreshing RACF classes on page 97 Changed information: v Setting up z/os security server RACF on page 93 For SA Changed information: v Added javahome attribute information to Options that affect Java on page 98. v Updated the summary and example at the end of Chapter 4, Preparing to use Internet service retrieval, on page 91. For SA New information: v What happens during internet service retrieval on page 15 v Requesting a new PTF order with the RECEIVE ORDER command on page 18 v Using internet service retrieval to request PTF or HOLDDATA: RECEIVE ORDER on page 42 v Chapter 4, Preparing to use Internet service retrieval, on page 91 Changed information: v Chapter 7, Installing preventive service, on page 125 v Chapter 8, Installing corrective service, on page 139 v Chapter 10, Managing exception SYSMODs, on page 151 v Chapter 12, Displaying the data managed by SMP/E: The LIST command, on page 165 v Chapter 13, Changing the data SMP/E manages: The UCLIN command, on page 171 Summary of changes xix

20 xx SMP/E V3R6.0 for z/os V2R3 User's Guide

21 Chapter 1. SMP/E primer This chapter provides an introduction to SMP/E to new SMP/E users. If you are already familiar with SMP/E, you can skip this chapter. What is SMP/E, and why should I use it? SMP/E is a tool designed to manage the installation of software products on your z/os system and to track the modifications you make to those products. Usually, it is the system programmer's responsibility to ensure that all software products and their modifications are properly installed on the system. The system programmer also has to ensure that all products are installed at the proper level so all elements of the system can work together. At first, that might not sound too difficult, but as the complexity of the software configuration increases, so does the task of monitoring all the elements of the system. To better understand this, let's take a closer look at your z/os system and see how SMP/E can help you maintain it. Understanding your system Your z/os system might appear to be one large block of code that drives your CPU. Actually, z/os is a complex system comprising many different smaller blocks of code. Each of those smaller blocks of code perform a specific function within the system. For example, some of the functions that can appear in a z/os system include: v Base Control Program (BCP) v C/C++ IBM Open Class Library v z/os Communications Server v Cryptographic Services v DFSMSdfp v DFSORT v Distributed File Service v Hardware Configuration Definition (HCD) v High Level Assembler (HLASM) v IBM HTTP Server v Infoprint Server v ISPF v JES2 or JES3 v z/os Language Environment v Network File System v Open Systems Adapter/Support Facility (OSA/SF) v Resource Measurement Facility (RMF ) v System Display and Search Facility (SDSF) v SMP/E v Time Sharing Option/Extensions (TSO/E) v z/os UNIX System Services (z/os UNIX) Copyright IBM Corp. 1986,

22 Introduction Each system function is composed of one or more load modules. In a z/os environment, a load module represents the basic unit of machine-readable, executable code. Load modules are created by combining one or more object modules and processing them with a link-edit utility. The link-editing of modules is a process that resolves external references and addresses. The functions on your system, therefore, are one or more object modules that were combined and link-edited. To see where the object modules come from, llook at the example in Figure 1. Figure 1. Creating load modules Most of the time, object modules are sent to you as part of a product. In this example, the object module MOD1 was sent as part of the product. Other times, you might need to assemble source code sent to you by product packagers to create the object module. You can modify the source code and then assemble it to produce an object module. In the example, SRCMOD2 is source code that you assemble to create object module MOD2. When assembled, you link-edit object module MOD2 with object module MOD1 to form the load module LMOD1. In addition to object modules and source code, most products distribute many additional parts, such as macros, help panels, dialog elements, and other z/os library members. These modules, macros, and other types of data and code are the basic building blocks of your system. All of these building blocks are called elements. Changing the elements of the system Over time, you may need to change some of the elements of your system. These changes may be necessary to improve the usability or reliability of a product. You may want to add some new functions to your system, upgrade some of the elements of your system, or modify some elements for various reasons. In all cases, you are making system modifications. In SMP/E, we refer to these system modifications as SYSMODs. A SYSMOD is the actual package containing information SMP/E needs to install and track system modifications. SYSMODs are composed of two parts: v Modification control statements (MCS), designated by ++ as the first two characters, that tell SMP/E: What elements are being updated or replaced 2 SMP/E V3R6.0 for z/os V2R3 User's Guide

23 Introduction How the SYSMOD relates to product software and other SYSMODs Other specific installation information v Modification text, which is the object modules, macros, and other elements supplied by the SYSMOD There are four different categories of SYSMODs, each supporting a task you might want to perform: Function SYSMODs Introduce the elements for a product. PTF (program temporary fix) SYSMODs Prevent or fix problems with an element, or introduce new element s. APAR (authorized program analysis reports) SYSMODs Fix problems with an element. USERMOD (user modifications) SYSMODs Customize an element. Introducing an element the function SYSMOD One way you can modify your system is to introduce new elements into that system. To accomplish this with SMP/E, you can install a function SYSMOD. The function SYSMOD introduces a new product, a new version or release of a product, or updated functions for an existing product into the system. All other types of SYSMODs are dependent upon the function SYSMOD, because they are all modifications of the elements originally introduced by the function SYSMOD. When we refer to installing a function SYSMOD, we are referring to the placing of all the product's elements in the system data sets, or libraries. Examples of these libraries are SYS1.LPALIB, SYS1.MIGLIB, and SYS1.SVCLIB. Figure 2 depicts the process of creating executable code in the production system libraries. Figure 2. Introducing an element Chapter 1. SMP/E primer 3

24 Introduction In this figure, the installation of a function SYSMOD link-edits object modules MOD1, MOD2, MOD3, and MOD4 to create load module LMOD2. The executable code created in load module LMOD2 is installed in the system libraries through the installation of the function SYSMOD. There are two types of function SYSMODs: v A base function SYSMOD adds or replaces an entire system function. Examples of base functions are SMP/E and JES2. v A dependent function SYSMOD provides an addition to an existing system function. It is called dependent because its installation depends upon a base function already being installed. Examples of dependent functions are the language features for SMP/E. Both base function SYSMODs and dependent function SYSMODs are used to introduce new elements into the system. Here's an example of a simple function SYSMOD that introduces four elements: ++FUNCTION(FUN0001) /* SYSMOD type and identifier. */. ++VER(Z038) /* For MVS SREL */. ++MOD(MOD1) RELFILE(1) /* Introduce this module */ DISTLIB(AOSFB) /* in this distribution library. */. ++MOD(MOD2) RELFILE(1) /* Introduce this module */ DISTLIB(AOSFB) /* in this distribution library. */. ++MOD(MOD3) RELFILE(1) /* Introduce this module */ DISTLIB(AOSFB) /* in this distribution library. */. ++MOD(MOD4) RELFILE(1) /* Introduce this module */ DISTLIB(AOSFB) /* in this distribution library. */. Preventing or fixing problems with an element the PTF SYSMOD When a problem with a software element is discovered, IBM supplies its customers with a tested fix for that problem. This fix comes in the form of a program temporary fix (PTF). Although you may not have experienced the problem the PTF is intended to prevent, it is wise to install the PTF on your system. The PTF SYSMOD is used to install the PTF, thereby preventing the occurrence of that problem on your system. Typically, PTFs are designed to replace or update one or more complete elements of a system function. Let's look at Figure 3 on page 5. 4 SMP/E V3R6.0 for z/os V2R3 User's Guide

25 Introduction Figure 3. Preventing problems with an element In Figure 3, we see a previously installed load module, LMOD2. If we want to replace the element MOD1, we should install a PTF SYSMOD that contains the module MOD1. That PTF SYSMOD replaces the element in error with the corrected element. As part of the installation of the PTF SYSMOD, SMP/E relinks LMOD2 to include the new and corrected version of MOD1. Here is an example of a simple PTF SYSMOD: ++PTF(PTF0001) /* SYSMOD type and identifier. */. ++VER(Z038) FMID(FUN0001) /* Apply to this product. */. ++MOD(MOD1) /* Replace this module */ DISTLIB(AOSFB) /* in this distribution library. */ object code for module... PTF SYSMODs are always dependent upon the installation of a function SYSMOD. In some cases, some PTF SYSMODs may also be dependent upon the installation of other PTF SYSMODs. These dependencies are called prerequisites. We will look at a typical PTF prerequisite when we discuss the complexity of keeping track of the elements of the system. Fixing problems with an element the APAR SYSMOD You may sometimes find it is necessary to correct a serious problem that occurs on your system before a PTF is ready for distribution. In this situation, IBM supplies you with an authorized program analysis report (APAR). An APAR is a fix designed to quickly correct a specific area of an element or replace an element in error. You install an APAR SYSMOD to implement a fix, thereby updating the incorrect element. In Figure 4 on page 6, the shaded section shows an area of MOD2 containing an error. Chapter 1. SMP/E primer 5

26 Introduction Figure 4. Fixing problems with an element The processing of the APAR SYSMOD provides a modification for object module MOD2. During the installation of the APAR SYSMOD, MOD2 is updated (and corrected) in load module LMOD2. Here is an example of a simple APAR SYSMOD: ++APAR(APAR001) /* SYSMOD type and identifier. */. ++VER(Z038) FMID(FUN0001) /* Apply to this product */ PRE(UZ00004) /* at this service level. */. ++ZAP(MOD2) /* Update this module */ DISTLIB(AOSFB) /* in this distribution library. */ zap control statements... The APAR SYSMOD always has the installation of a function SYSMOD as a prerequisite, and can also be dependent upon the installation of other PTF or APAR SYSMODs. Customizing an element the USERMOD SYSMOD If you had a requirement for a product to perform differently from the way it was designed, you might want to customize that element of your system. IBM provides you with certain modules that allow you to tailor IBM code to meet your specific needs. After making the desired changes, you add these modules to your system by installing a USERMOD SYSMOD. This SYSMOD can be used to replace or update an element, or to introduce a totally new user-written element into the system. In either case, the USERMOD SYSMOD is built by you either to change IBM code or to add your own code to the system. In Figure 5 on page 7, MOD3 was updated through the installation of a USERMOD SYSMOD. 6 SMP/E V3R6.0 for z/os V2R3 User's Guide

27 Introduction Figure 5. Customizing an element Here is an example of a simple USERMOD SYSMOD: ++USERMOD(USRMOD1) /* SYSMOD type and identifier. */. ++VER(Z038) FMID(FUN0001) /* Apply to this product */ PRE(UZ00004) /* at this service level. */. ++SRCUPD(JESMOD3) /* Update this source module */ DISTLIB(AOSFB) /* in this distribution library. */ update control statements... Prerequisites for USERMOD SYSMODs are the installation of a function SYSMOD, and possibly the installation of other PTF, APAR, or USERMOD SYSMODs. SYSMOD prerequisites As you have learned, PTF, APAR, and USERMOD SYSMODs all have the function SYSMOD as a prerequisite. In addition to their dependencies on the function SYSMOD: v PTF SYSMODs may be dependent upon other PTF SYSMODs. v APAR SYSMODs may be dependent upon PTF SYSMODs and other APAR SYSMODs. v USERMOD SYSMODs may be dependent upon PTF SYSMODs, APAR SYSMODs, and other USERMOD SYSMODs. Consider the complexity of these dependencies. When you multiply that complexity by hundreds of load modules in dozens of libraries, the need for a tool like SMP/E becomes apparent. Let's examine the impact of these dependencies on the maintenance of software in a z/os environment. Keeping track of the elements of the system The importance of keeping track of system elements and their modifications becomes readily apparent when we examine the z/os maintenance process. Often, a PTF contains multiple element replacements. In the example in Figure 6 on page 8, PTF1 contains replacements for two modules, MOD1 and MOD2. Although load module LMOD2 contains four modules, only two of those modules are being replaced. Chapter 1. SMP/E primer 7

28 Introduction Figure 6. PTF replacement But what happens if a second PTF replaces some of the code in a module that was replaced by PTF1? Let's look at Figure 7. Figure 7. PTF prerequisite In this example, PTF2 contains replacements for MOD2 and MOD3. For MOD1, MOD2, and MOD3 to interface successfully, PTF1 must be installed before PTF2. That's because MOD3 supplied in PTF2 may depend on the PTF1 version of MOD1 to be present. It is this dependency that constitutes a prerequisite. SYSMOD prerequisites are identified in the modification control statements (MCS) part of the SYSMOD package we discussed in Changing the elements of the system on page 2. In addition to tracking prerequisites, there is another important reason to track system elements. The same module is often part of many different load modules. Let's take a look at the example in Figure 8 on page 9. 8 SMP/E V3R6.0 for z/os V2R3 User's Guide

29 Introduction Figure 8. Load module constructions How does SMP/E work? In Figure 8, the same MOD2 module is present in LMOD1, LMOD2, and LMOD3. When a PTF is introduced that replaces the element MOD2, that module must be replaced in all the load modules in which it exists. Therefore, it is imperative that we keep track of all load modules and the modules they contain. You can now appreciate how complicated the tracking of system elements and their modification levels can become. Let's take a brief look at how we implement the tracking capabilities of SMP/E. Tracking and controlling requisites To track and control elements successfully, all elements and their modifications and updates must be clearly identified to SMP/E. SMP/E relies on modification identifiers to accomplish this. There are three modification identifiers associated with each element: v Function modification identifiers (FMIDs) that identify the function SYSMOD that introduced the element into the system. v Replacement modification identifiers (RMIDs) that identify the last SYSMOD (usually a PTF SYSMOD) to replace the element. v Update modification identifiers (UMIDs) that identify the SYSMODs that have updated an element since it was last replaced. SMP/E uses these modification identifiers to track all SYSMODs installed on your system. This ensures that they are installed in the proper sequence. Now that we realize the need for element tracking and know the types of things SMP/E tracks, let's look at how SMP/E performs its tracking function. Let's review our discussion of how functions are installed into the system. We begin with elements, such as modules, macros, and source code. These elements are then processed by utilities, such as an assembler or link-editor, to create load modules. The load modules contain the machine-readable, executable code. Chapter 1. SMP/E primer 9

30 How SMP/E works Your production system in a z/os environment consists of the z/os operating system and all the code needed to do your everyday work. That's fine, but where is all that stuff kept, and how is it organized? Let's find out. The distribution and target libraries To properly perform its processing, SMP/E must maintain a great deal of information about the structure, content, and modification status of the software it manages. Think of all the information SMP/E has to maintain as if it were all the information contained in the public library. To follow this analogy, let's refer to Figure 9. Figure 9. The public library If you look at this figure depicting the public library, you see bookshelves filled with books and a card catalog with drawers containing a card for each book in the library. These cards contain information, such as the title, author, publishing dates, type of book, and a pointer to the actual book on the shelf. In the SMP/E environment, there are two distinct types of bookshelves. They are referred to as the distribution libraries and the target libraries. Figure 10 on page 11 depicts these two types of SMP/E libraries. 10 SMP/E V3R6.0 for z/os V2R3 User's Guide

31 How SMP/E works Figure 10. The distribution and target libraries In much the same way the bookshelves in the public library hold the library books, the distribution and target libraries hold the elements of the system. Distribution libraries contain all the elements, such as modules and macros, that are used as input for running your system. One very important use of the distribution libraries is for backup. Should a serious error occur with an element on the production system, the element can be replaced by a stable level found in the distribution libraries. Target libraries contain all the executable code needed to run the system. The consolidated software inventory (CSI) As you refer to the analogy of the public library, you can see that there is one important piece of Figure 9 on page 10 that we have not yet considered. In the public library, there is a card catalog to help you find the book or piece of information you are looking for. SMP/E provides the same type of tracking mechanism in the form of the consolidated software inventory (CSI). The CSI data sets contain all the information SMP/E needs to track the distribution and target libraries. As the card catalog contains a card for each book in the library, the CSI contains an entry for each element in its libraries. The CSI entries contain the element name, type, history, how the element was introduced into the system, and a pointer to the element in the distribution and target libraries. The CSI does not contain the element itself, but rather a description of the element it represents. Let's see exactly how these entries are arranged in the CSI. The SMP/E zones The cards in the public library card catalog are arranged alphabetically by the author's last name, and by the topic and title of the book. In the CSI, entries for the elements in the distribution and target libraries are grouped according to their installation status. That is, entries representing elements found in the distribution libraries are contained in the distribution zone. Entries representing elements found in the target libraries are contained in the target zone. Both of these zones serve the same purpose as the drawers of the public library card catalog. In addition to the distribution and target zones, the SMP/E CSI also contains a global zone. The global zone contains: v Entries needed to identify and describe each target and distribution zone to SMP/E v Information about SMP/E processing options v Status information for all SYSMODs SMP/E has begun to process Chapter 1. SMP/E primer 11

32 How SMP/E works v Exception data for SYSMODs requiring special handling or that are in error In SMP/E, when we speak of exception data, we are usually referring to HOLDDATA. HOLDDATA is often supplied for a product to indicate a specified SYSMOD should be held from installation. Reasons for holding a SYSMOD can be: v A PTF is in error and should not be installed until the error is corrected (ERROR HOLD). v Certain system actions may be required before SYSMOD installation (SYSTEM HOLD). v The user may want to perform some actions before installing the SYSMOD (USER HOLD). All the information found in the global zone, combined with the information found in the distribution and target zones, represents the data SMP/E needs to install and track your system software. Remember the picture of the public library in Figure 9 on page 10? Now look at Figure 11. Figure 11. z/os system with SMP/E Now you can see how all the elements of the system fit together, and how they can be installed, modified, and tracked using SMP/E. What are the basic SMP/E commands I need to know? Now that you are familiar with SMP/E and what it can do, you are probably wondering what you need to know to get started using SMP/E. Let's take a look at the basic processing commands you need to know to use SMP/E. 12 SMP/E V3R6.0 for z/os V2R3 User's Guide

33 Basic SMP/E commands Setting the zone you want to work on Before processing SMP/E commands, you must first set the zone on which you want SMP/E to work (global, target, or distribution). You do this by issuing the SET command. The SET command identifies the zone and, therefore, the libraries, upon which subsequent SMP/E commands are to act. The SET command can also be used to request a particular set of predefined processing options. For more information about the SET command, see SMP/E for z/os Commands. Receiving the SYSMOD into SMP/E's data sets For SMP/E to install a SYSMOD, the SYSMOD must be received into data sets that can be used by SMP/E. The SMP/E RECEIVE command performs the task of copying the SYSMOD from the distribution medium from which it was sent into the data sets used by SMP/E. For more information about the RECEIVE command, refer to Receiving the SYSMOD into SMP/E's data sets on page 14. Applying the SYSMOD to the target libraries Once a SYSMOD has been received, you want to apply the SYSMOD to the appropriate target libraries. The SMP/E APPLY command invokes various system utilities to install the SYSMOD's elements into the target libraries. For more information about the APPLY command, refer to Applying the SYSMOD to the target libraries on page 19. Restoring the target libraries to the previous level Should you experience problems after applying a SYSMOD, you may want to restore its elements in error to a previous and stable level. The SMP/E RESTORE command replaces a failing element with a copy from the distribution libraries. For more information about the RESTORE command, refer to Restoring the target libraries to the previous level on page 23. Accepting the SYSMOD and updating the distribution libraries After you have performed a SYSMOD RECEIVE and APPLY, you want to accept the elements into the distribution libraries for backup. However, this should be done only after you are satisfied with the performance and stability of the elements of the SYSMOD. Once you ACCEPT a SYSMOD, you cannot RESTORE its element to a previous level. The SMP/E ACCEPT command updates the distribution libraries so they are available for backup of any future SYSMODs. For more information about the ACCEPT command, refer to Accepting the SYSMOD into the distribution libraries on page 27. Displaying SMP/E data The SMP/E CSI and other primary data sets contain a great deal of information you may find useful when installing new elements or functions, preparing user modifications, or debugging problems. You can display that information, as well as information about modules, macros, and other elements, in several different ways. v Query dialogs display specific information you request through interactive dialogs with SMP/E. Chapter 1. SMP/E primer 13