SMP DEMYSTIFIED: Part II By Sam Golob Modification Control Statements Now is a good time to mention the syntax of SMP Modification Control Statements, before going into the details of RECEIVE, APPLY, and ACCEPT processing. Rule number one is that all SYSMOD control statements (known in IBMese as MCS) must begin with the characters ++ in columns 1 and 2 of the SYSMOD's card-image records. The other keywords and parameters in SYSMOD syntax are free-flowing. Extra blanks don't count. Columns 73 to 80 are not used in the SYSMOD statements themselves, but are required for IEBUPDTE source and macro update cards. A SYSMOD cannot be renumbered. Comments are as in the PL/I language, they begin with the characters /* and end with the characters */. Everything in between these characters, even on many successive lines, is treated by SMP as a comment. All SMP statements must end in a period. The period is the delimiter for statements in SMP syntax, and one must be exceedingly careful with them. Every SYSMOD must begin with the statements: ++ FUNCTION, ++ PTF, ++ APAR, or ++ USERMOD, followed by the seven character SYSMOD ID enclosed in parentheses, and delimited by a period. FUNCTION SYSMODS have already been covered in the first part of this article (Technical Support, December 1988). PTF SYSMODS or PTFs are (after the invention of SMP and the change in IBM's maintenance philosophy) really permanent system fixes, even though their name stands for Program Temporary Fix. The temporary fixes are now called APARs, which is really a short term for APAR FIX. APAR stands for Authorized Program Analysis Report, and it refers to a problem that was reported to IBM. IBM assigns a number to each problem, and when the problem is fixed, the temporary fix itself is assigned the same number. This number (or something very close to it) is what SMP uses for the APAR SYSMOD ID. APAR SYSMODS are intended to be replaced, or superseded, by permanent fixes, or PTFs. They are therefore not usually ACCEPTed into the Distribution Libraries. USERMODs are packaged SMP SYSMODS written by the individual installation, usually to modify some IBM code. They look like PTFs or APARs, but SMP puts them in a special category so that they stay a bit distant from the real IBM maintenance. The user has flexibility to assign almost any seven character SYSMOD ID to a USERMOD, but each different SYSMOD must have a unique ID, and it is wise to steer clear of IBM-type names. USERMODs are also usually not ACCEPTed into IBM Distribution Libraries (also known as DLIBs) because they are likely to overlay IBM code there. USERMODs should only be ACCEPTed if you really know what you are doing. I'll quickly explain the concepts of other keywords you're likely to find at the top of SMP SYSMODS. I don't intend to be exhaustive. The idea is to cut through the ice and give you some idea of what is happening. ++ VER means version of the operating system, or perhaps "domain of SMP activity" would also be an appropriate explanation. The values for this parameter have four characters, and there aren't too many valid choices. Z038 means MVS 3.8 and upwards through XA. (Z037 or MVS 3.7 probably isn't used anymore.) C150 means CICS 1.5 and upward. These values almost never change, and within the same domain of activity, you always find the same value. The ++VER values were originally intended to differentiate between similar maintenance on different MVS releases, but because of the evolution of the SMP product since those days, it isn't as important any more. The purpose of the ++VER statement has been largely taken over by the FMID. It is still required, however, and must be included in all SYSMODs. Inside the ++VER statement are the FMID, PRE, REQ, and SUP keywords. FMID has been discussed. Every SYSMOD must belong to a unique FMID. In the parentheses following the FMID keyword, the FMID which will own the SYSMOD must be specified. PRE and SUP are quite simple. In the parentheses following the PRE keyword, and separated by spaces or commas, is a list of SYSMOD IDs which have to be present before the new SYSMOD can be APPLYed. The prerequisite SYSMODs must have been already APPLYed themselves, or else they have to be APPLYed together with this new SYSMOD. If all the PREs or prerequisites are not present, the new SYSMOD will not go on. REQ is like PRE, but the SYSMODs that are REQuired for the new SYSMOD, must be APPLYed in the same run as the new SYSMOD. It is seldom necessary to use the REQ keyword, usually PRE will suffice. Following the SUP keyword is a list of SYSMODS that are effectively replaced, or SUPERSEDED by the new SYSMOD. SUP is used when the intent of the new material is to completely obsolete all the material from all of the SYSMODs in the SUP list. If only some of the material in a previous SYSMOD or PTF will be replaced, that SYSMOD should be placed in the PRE list or prerequisite list. For a SYSMOD to be superseded or SUPed (to use the common parlance) its purpose in the operating system should be completely replaced by the later SYSMOD. The new SYSMOD may have a sequence of ++IF FMID(fmidnam) THEN REQ(sysmdid) statements. This happens if different levels of the same product exist, as mentioned earlier regarding the various MVS/370 product levels. If the new SYSMOD is for a lower level of the product, and the installation has both that level and a higher level, it may be necessary to apply another fix to satisfy the requirements of the higher level. SMP is informed of this by a coded ++IF statement in the lower level SYSMOD. If the higher level referred to in the ++IF statement is not present on the system, then the fix suffices, and it will go on to the system normally. If the installation has the higher level of the product also, the lower level SYSMOD will not go on without the presence of the SYSMOD ID in the REQ keyword of the ++IF statement. The FMID name within the ++IF statement is usually for a higher level of the product than the current SYSMOD is for. Below all this VER, PRE, SUP and IF stuff is the actual fix. A ++MOD statement followed by object code signifies an object module replacement of a CSECT. A ++SRC statement followed by source code is a complete source code replacement. A ++MAC statement is followed by the complete replacement for the macro. A ++SRCUPD statement or ++ MACUPD statement followed by IEBUPDTE control cards signifies updates to an existing source module or macro. Keywords in these statements supply necessary additional instructions so that the change is done according to the author's or IBM's specifications. Specification of the destination libraries for the ELEMENT to be changed is also accomplished by these keywords. A single SYSMOD can contain fixes for many system ELEMENTs. Each ELEMENT to be changed must have its own ++SRC, ++MOD, +SRCUPD, ++MAC or ++MACUPD control card, followed by the replacement or additional material for that ELEMENT. An approximate limit to the number of element fixes in one SYSMOD is set by a global SMP parameter called PEMAX. It is advisable to set PEMAX to a high number, usually 9999. One more important note. Libraries in SMP control statements are referred to by their DDNAMES only, which are one to eight characters long. It is a safe and wise practice in SMP work to always make the DDNAME of the library correspond to the lowest-level qualifier of its dataset name. Dataset name prefixes don't count to the SMP program. It is therefore advisable to use the same SMP JCL procedure when doing system modifications to one system. The JCL of that PROC will uniquely and unchangeably determine the destination libraries of the SMP action. Thus, the SMP control information and the actual contents of the affected libraries will always be kept in synchronization. (SMP/E has a facility for determining dataset names by dynamic allocation. These dynamically determined library names are called DDDEFs. DDDEFS, dynamically accomplish what DD cards do in a JCL procedure.) The SMP Work Flow The discussion of control datasets is based on the three processes of SMP flow. These are RECEIVE, APPLY, and ACCEPT. RECEIVE, APPLY, and ACCEPT are the SMP- language equivalents of: taking a new SYSMOD into the SMP environment, putting its pieces into the Target Libraries in the proper places, and finally, storing its pieces in the Distribution Libraries for archival and possible later use. Again, the flow is: IBM-supplied SYSMODS, to Target Libraries, to Distribution Libraries. How do the RECEIVE, APPLY, and ACCEPT processes work? I will discuss these processes briefly in order, with the aim of keeping the discussion conceptual. Once the concepts are understood, and the vocabulary words associated with them are learned, then the IBM literature will become readable. RECEIVE RECEIVE basically involves storing a new SYSMOD and recording some vital statistics about it, so that it is pre-digested by SMP. The text of the entire SYSMOD is stored in a partitioned dataset called the PTS, or PTF Temporary Store dataset. In the older version of SMP, SMP4, the control information taken during the RECEIVE process is stored in the PTS also. However, in SMP/E, all control information is stored in VSAM files known as ZONEs. The VSAM file which stores the control information from the RECEIVE process is known as the GLOBAL ZONE. The text of the SYSMOD thus goes to the PTS as before, but the control information is stored in the GLOBAL ZONE. Certain SYSMODS are RECEIVEd a bit differently. These are SYSMODS which have what are known in SMP language as RELFILE. The word RELFILE roughly translates to IEBCOPY. If a modification has large numbers of linkedited csects, macros, ISPF panels, or other ELEMENTs, which are suitable for direct IEBCOPY into Target Libraries, then those ELEMENTs included in the SYSMOD which have similar record format and record length can be loaded into a single PDS. This PDS is unloaded onto the SYSMOD distribution tape using IEBCOPY, and its file sequence order on the tape is very important. If the Sysmod Specification File on the tape (known as the SMPMCS) calls for three RELFILEs for instance, then the next three files on the tape, hopefully IEBCOPY unloaded, are known as RELFILE(1), RELFILE(2), and RELFILE(3) respectively. The RECEIVE process on a SYSMOD with RELFILE is the following: The SMPMCS, which contains the SMP control statements of the SYSMOD, is read from the tape. The number of RELFILEs (three in this example) is determined from the RELFILES (3) keyword in the SMPMCS. The three files on the tape which follow the SMPMCS file are then unloaded to a disk pack (determined by the SMPTLIB DD statement in the SMP job) and given special names, which SMP will understand during later APPLY and ACCEPT processing of the SYSMOD. These names are of the format: prefix.sysmodid.Fn, where n is 1, for the first relfile, 2 for the second, and so forth. The prefix is set in the GLOBAL ZONE for SMP/E (or in the PTS system entry in SMP4) and is not changed during the entire process. When a SYSMOD with RELFILEs is RECEIVEd, the Relfile Libraries are loaded from tape to disk. The elements they contain are thus readied, so that the APPLY and ACCEPT processes to follow can selectively copy them to where they will be needed. Meanwhile, the SMPMCS is itself copied to the PTS, and its control information is dealt with as discussed before. With SMP/E there is a bit more to the RECEIVE process. Besides the RECEIVE of SYSMODS, one must also RECEIVE SYSMOD error information. This is known as HOLDDATA. HOLDDATA consists of a list of ++HOLD and ++RELEASE control statements in sequential order. Each of these statements point to a PTF or an APAR SYSMOD. The purpose of the ++HOLD statement is to prevent SMP/E from APPLYing a PTF that is in error, known as a PE PTF. A ++RELEASE statement that is RECEIVED after a ++HOLD statement against the same SYSMOD will undo the effect of the ++HOLD statement. The order in which the statements are RECEIVED is of paramount importance. SMP/E will honor the ++RELEASE only if it occurs after all ++HOLD statements for that particular SYSMOD. The HOLDDATA is kept in the SMP/E GLOBAL ZONE. A quick word about undoing the RECEIVE of a SYSMOD. A RECEIVE can be undone by an SMP process called REJECT. To REJECT a SYSMOD that has been RECEIVEd causes the SYSMOD to be erased from the PTS and its control information associated with the RECEIVE process to be wiped out. If the SYSMOD has RELFILEs, the disk-loaded copies are deleted. The SYSMOD cannot then be APPLIED or ACCEPTED unless it is re-RECEIVED. REJECTing a SYSMOD will not affect the status of a SYSMOD that has already been APPLYed or ACCEPTed. It stays in the Target Libraries and in the Distribution Libraries. APPLY Now once a SYSMOD is RECEIVEd, how is it APPLYed to the Target Libraries? When thinking about APPLYing SYSMODS to your system, never forget that the purpose of a SYSMOD is to supply new components for the operating system or a product. The APPLY process puts the new pieces or elements into their proper places in the executing libraries of the system, the Target Libraries. It also keeps detailed track of what was done. APPLY can only be done to a SYSMOD that has been RECEIVEd. The RECEIVE process has put the SYSMOD into the SMP staging areas, the PTS, and possibly the unloading RELFILE, and has done some preliminary accounting in the SMP/E GLOBAL ZONE or the SMP4 PTS. The APPLY process will pick up the SYSMOD from there. Accounting for the APPLY process is done in SMP/E using a VSAM cluster called the TARGET ZONE, and in SMP4 using several partitioned datasets, the most important of which is called the CDS or Control Data Set. A word about ELEMENT accounting. If a SYSMOD will replace an ELEMENT, that ELEMENT acquires an RMID (Replacement Module ID) equal to the SYSMOD ID of the SYSMOD which replaced it. Since the piece was completely replaced, each MAC, MOD, or SRC ELEMENT can have only one RMID. If on the other hand, the SYSMOD will update a MACRO, update SOURCE, or zap a LOAD MODULE, then that ELEMENT acquires a UMID (Update Module ID) equal to the SYSMOD ID that updated it. One macro or module can have many UMIDS, because it is possible to update a single ELEMENT many times. Now back to APPLY processing. Many SYSMODS can be APPLYed together in one run. This is one of the great conveniences of the SMP product. The programmer can select a list of individual SYSMODS by their seven-character SYSMOD IDs in the SMPCNTL DD statement, where the APPLY parameter is entered into the SMP job. This is accomplished simply by stating APPLY SELECT (sysmdid,sysmdid, ...).. Just one SYSMOD can be selected to APPLY, if that is what is desired. It is almost always advisable to do APPLY CHECK before doing the real APPLY. APPLY CHECK is a dry run of the APPLY process. All SMP control information will be verified, just as if the real APPLY was being done. With APPLY CHECK however, no real library updates are done, and the SYSMODS will not really be APPLYed to the system. A report will be generated that tells what would be done. ACCEPT and RESTORE processing, to be mentioned later, also have the CHECK facility. It is also possible to do what is called a MASS APPLY. By simply stating the word APPLY in the SMPCNTL DD statement of an SMP job, SMP will attempt to APPLY all RECEIVEd SYSMODS that are eligible for the system but have not been APPLYed yet. SMP will look at all the un-APPLYed RECEIVEd SYSMODS and will build a SYSMOD SELECT list. SMP will then proceed to APPLY all the selected SYSMODS to the system. It is possible to EXCLUDE a list of SYSMODS specifically from a MASS APPLY, by using the EXCLUDE or E parameter in the APPLY control statement. In SMP/E (but not in SMP4) there is an additional way to exclude a SYSMOD from an APPLY. This is through a ++HOLD modification control statement which has been RECEIVEd previous to the APPLY request. MASS APPLY is the normal means of APPLYing IBM's periodic system maintenance known as PUTs (Program Update Tapes) to the system, because this maintenance consists of large numbers of PTFs, perhaps several hundred of them, and it is inconvenient to SELECT them individually. There is another APPLY option called APPLY GROUP. APPLY GROUP works very much like APPLY SELECT for APPLYing a list of SYSMODS. The difference concerns missing prerequisites. If APPLY GROUP(sysmdid,...) is coded instead of APPLY SELECT, SMP will go to the trouble of adding all necessary prerequisites to the SELECT list before doing the APPLY. It is only necessary that the added SYSMODS have been previously RECEIVEd. APPLY GROUP is handy for APPLYing new PTFs when information is unknown about other necessary PTFs. This option does use extra overhead, but it can be used to avoid multiple SMP runs when some prerequisites may be missing. BYPASS is a useful facility of SMP APPLY processing, especially during APPLY CHECK for determining if the APPLY should work. The BYPASS parameter (also available with ACCEPT) of APPLY allows SYSMODS to be APPLYed to the system, even though prerequisites or other requirements are missing. During a real APPLY situation, the BYPASS parameter will allow putting on a SYSMOD in an exceptional circumstance, when there is no other way of getting it on. During a CHECK situation however, it is advisable to BYPASS all or most error conditions on the first try. This is because SMP will often stop further action when it encounters the first ERROR. For instance, suppose SYSMODS B and C both require SYSMOD A, and SYSMOD A has a ++HOLD against it. When trying to APPLY CHECK SELECT SYSMODS A, B, and C together, without a BYPASS (HOLDERROR) coded, SMP will not indicate how the three SYSMODS will APPLY, and what ELEMENTs they will affect. SMP will simply say that it cannot APPLY SYSMODS B and C because it could not APPLY SYSMOD A. On the next try, if a BYPASS (HOLDERROR) is coded in the APPLY CHECK, SMP/E would give a complete report of the ELEMENTs affected by all three SYSMODS, because the BYPASS allowed the simulation of a completed APPLY, and all the consequences of the APPLY will show in the report. As a matter of procedure, most people BYPASS every error condition during APPLY CHECK, but some try not to use BYPASS on the real APPLY. They exert much effort to completely clean up the APPLY CHECK so they can avoid coding a BYPASS for the real APPLY run. I personally leave the BYPASS in during the real APPLY runs too. I just make sure that the APPLY CHECK will show the exact result that I want to achieve. My approach avoids an excessive number of APPLY CHECK runs, which can take a long time. This is a matter of personal preference. The important thing is that the real APPLY should always be done with the same parameters as the last satisfactory APPLY CHECK run. The final point on APPLY processing is to show how the pattern of the system is determined or changed during APPLY. System patterns are communicated to SMP by means of the JCLIN facility. JCLIN consists of MODEL JCL statements for ASSEMBLY, LINKEDIT or COPY steps. SMP reads these statements, and uses them to determine how source can be reassembled after a MACRO change, or how load modules of one or many csects (called LMODs by SMP) are linkedited from component parts, including all linkedit control statements and attributes. JCLIN is only associated with Target Libraries and the TARGET ZONE, not with Distribution Libraries, which have only separate pieces of the system. JCLIN tells SMP how to construct the working programs of the system from their component pieces. This is reminiscent of our discussion of the SYSGEN process. In fact, JCLIN is the means of communicating the contents of the SYSGEN STAGE II DECK to SMP. A JCLIN stream can be put into SMP in two ways. The first way is by means of a dataset of JCL, which is referred to in the SMP job by the SMPJCLIN DD statement. The second means is from within a SYSMOD itself. This second way is called INLINE JCLIN. The JCL stream is included in the text of the SYSMOD and preceded with a ++ JCLIN statement. This will cause the JCL pattern to be read into the TARGET ZONE or CDS when the SYSMOD is APPLYed. RESTORE The APPLY process is reversed with the RESTORE process. RESTORE takes off SYSMODS that have already been APPLYed but not ACCEPTed. SMP provides a RESTORE CHECK facility so the user can determine in advance if the RESTORE will work. RESTORE allows bad SYSMODS to be backed off if they are causing trouble during system tests, after APPLYs have been done. ACCEPT The ACCEPT process of SMP takes the ELEMENT replacements which have already been APPLYed to the system (and presumably tested), and puts them into the Distribution Libraries to archive them. This also allows them to be used in a subsequent SYSGEN or IOGEN (a partial SYSGEN to rearrange IO-configuration related ELEMENTS). ACCEPT is thus a very important process. Control information for the ACCEPT processing is kept, for SMP/E, in a VSAM cluster known as a DLIB ZONE. Each DLIB ZONE must be paired with a corresponding TARGET ZONE. This is because SMP will normally ACCEPT only SYSMODS that have already been APPLYed, and the TARGET ZONE has the control information for the APPLYed SYSMODS. It is possible for one GLOBAL ZONE to control several pairs of TARGET and DLIB ZONES, so that several sets of system libraries can be maintained out of one SMP/E configuration. For SMP4, control information for ACCEPT is kept in two partitioned datasets, the ACDS (Alternate Control Data Set) and the ACRQ (Alternate Conditional Requisite Queue Data Set). There is also a CRQ dataset for APPLY information. These datasets correspond to the information that is kept in the DLIB ZONE for SMP/E. ACCEPT control parameters are similar to those for APPLY, as discussed above. It is always advisable to do ACCEPT CHECK runs before doing a real ACCEPT run, just to make sure the job will achieve the desired result. Doing ACCEPT CHECK runs will make it possible to fix errors before the ACCEPT run. Once a SYSMOD has been ACCEPTed on the SYSTEM, it cannot be removed, except by another SYSMOD that will supersede it and replace all its ELEMENTS. In order for an ELEMENT to be used in a subsequent SYSGEN or IOGEN, its SYSMOD must first be ACCEPTed. This loads the ELEMENT into its proper Distribution Library. As stated before, the SYSGEN process uses the material in the DLIBS to build the system, and one doesn't want back-level code to creep into the system after an IOGEN has been done. It is therefore mandatory to do a MASS ACCEPT before a SYSGEN or IOGEN is done. There is a special case of ACCEPT processing which allows SMP to simulate the SYSGEN process. This type of ACCEPT processing is called ACCEPT NOAPPLY, and its purpose is to replace SYSGEN MACROS and other pieces of the Distribution Libraries so a newly updated SYSGEN STAGE II DECK can be created. This new STAGE II DECK will reflect the new pattern that IBM has planned for the new version of the operating system. ACCEPT NOAPPLY processing replenishes the DLIBS directly from RECEIVEd SYSMODS, bypassing the Target Libraries entirely. After the ACCEPT NOAPPLY has been done, and the DLIBS reflect the state of the new system, a STAGE II SYSGEN DECK is assembled from the installation's STAGE I DECK, and the new STAGE II DECK is made known to SMP through the JCLIN process. When a subsequent APPLY of the same SYSMODS is done, all their ELEMENTs will fit into the system according to their proper new pattern. UCLIN and LIST UCLIN for SMP control datasets roughly corresponds to ZAP for data. UCLIN provides the facility for arbitrarily changing SMP control information. Sometimes SMP control entries must be adjusted to allow a PTF to be APPLYed or ACCEPTed properly. For example, suppose PTF B is intended to replace ELEMENT A, but the installation has modified ELEMENT A with a USERMOD. The intention is to replace ELEMENT A with IBM's new version of it, supplied by PTF B. After the element is replaced, the USERMOD will be refitted to the new version. This is what is intended, but SMP will not allow it. That is because PTF B doesn't know, in its PRE and SUP keywords about the USERMOD, which tagged ELEMENT A with a UMID equal to the USERMOD's SYSMOD ID. The APPLY CHECK run to APPLY PTF B will report an ID CHECK, stopping PTF B from going on. One way to get around this situation is to use UCLIN processing to remove the strange UMID from ELEMENT A before doing the APPLY for PTF B. Then PTF B can be APPLYed without any trouble, and it will replace ELEMENT A on the system, achieving the desired result. (Another approach is to BYPASS ID CHECKS and force PTF B on. The UCLIN approach seems cleaner to me.) UCLIN can also be used to replace large pieces of SMP control data. SMP has a facility called UNLOAD, that converts entire SMP entries, or even an entire ZONE into UCLIN control statements. This may prove useful to some users. The UCLIN facility provides fine control on the SMP entries, outside of the RECEIVE, APPLY, ACCEPT milieu. Obviously, UCLIN should be used with extreme caution, and only by someone who knows exactly what they are doing. Sometimes an IBM-supplied PTF will recommend the application of UCLIN. This should also be done with care, because a previous SYSMOD may have done the proper adjustment already. LIST allows the SMP user to display all SMP control information, and it is obviously the tool to use for determining if UCLIN is necessary, and if your UCLIN worked properly. LIST also has considerable general-purpose use in SMP. It is the way to do SMP inquiry. With SMP4, it is practically the only way to find out SMP control information. (There are a few other tools around, including a LISTCDS TSO command on file 300 of the CBT tape.) With SMP/E, there is an extensive ISPF Inquiry System that takes the place of the LIST function for most routine lookups. LIST can still be used for big inquiries in batch. The SMP books have much information on the use of the LIST command. End Of Lesson Now you can try your hand at the SMP books. You'll probably find them clear and well-written now, because you're past the vocabulary barrier. Any words I haven't defined here can probably be found in the glossaries of the SMP publications, and you will be on your way. After you hit the books, you can use SMP carefully, but with confidence.