% % SHOW MERGED CLASSES TOOL DESCRIPTION % \input{read_general:[procedures]sesdfmt.tex} % Latex input file defining standard format \newcommand{\revision} {B} % latest revision letter % (e.g., A, B) % (seldom changes) \newcommand{\version} {1} % latest version % UPDATE THE VERSION EACH TIME THE DOCUMENT IS CHANGED, INCREMENTING BY 1 % STARTING WITH VERSION 1 \newcommand{\runningtitle}{Show Merged Classes Tool} % title for top of page \newcommand{\control} { SCI89148 } % ST ScI control number \newcommand{\modname} {{\bf smc.tex}} % file name in library \newcommand{\modlibe} {{\bf read\_tools:[sogs] }} % BROWSE directory \thispagestyle{empty} % No header or number on first page \markright{\runningtitle \hspace{1.0in} \revision \hspace{0.1in} \version \hspace{0.5in}} \begin{document} \vspace*{1in} \begin{center} {\Large{\bf Show Merged Classes Tool}}\footnote{This is module \modname{} in library \modlibe{}, printed \today} \\ \bigskip \begin{bf} \control \\ \revision\\ \bigskip \end{bf} \author \\ \bigskip \vspace*{2.0in} {\bf Abstract } \\ \bigskip \end{center} % FILL IN AN ABSTRACT % This is an abstract of the whole document. It should never be more than a % few sentences. The {\it Show Merged Classes \/}tool compares all of the elements in a CMS library class (typically an SPR class) to see if they are also inserted, or ``merged'' into another class (typically a PENDING class) in that same CMS library. \clearpage % Table of Contents page \tableofcontents % note that you may need to ``LaTeX'' a document twice after editing in order % to structure the table of contents properly. \clearpage \section{Introduction} The {\it Show Merged Classes \/} tool compares all of the elements in a CMS library class (typically an SPR class) to see if they are also inserted, or ``merged'' into another class (typically a PENDING class) in that same CMS library. When an SPR is being addressed in a CMS library, one or more files will be modified, and the modified element generations are placed into a specific SPR class. When the particular SPR is completed, and scheduled to be placed into a build, the element generations from the SPR class must also be placed into a PENDING class. It is the PENDING class from which files are fetched to do the build, so it is important that all updated elements be placed in this class. \section{Report Parts} The {\it Show Merged Classes \/} tool produces a report with the following information: % Bullet type list \begin{itemize} \item Merged/Unmerged Element Table \item SubClass List \item Questionable Descendants \item Reserved Pending Elements \end{itemize} \subsection{Merged/Unmerged Element Table} The {\it Show Merged Classes \/} tool produces a table that tells whether a specific SPR class is merged into a specific PENDING class. If the SPR class is not merged, it tells what elements from the SPR class were the culprits. An element is considered to be unmerged if either it does not exist by name or by the same generation number in the PENDING class. \subsection{SubClass List} Whenever an SPR class contains at least one element that is also in the PENDING class this SPR class is considered to be a PENDING SubClass. There may or may not be unmerged elements in this SPR class. The output report contains a list of PENDING SubClasses. This list is a quick reference of what SPRs are being addressed by a specific build in a CMS library. \subsection{Questionable Descendants} A questionable descendant is an element that is in the PENDING class that has been reserved and replaced SINCE it was inserted into the PENDING class. This may or may not be a problem. It is a problem if the later element generation is supposed to belong to that PENDING class, because build fetches on that element will pick up an earlier version. The {\it Show Merged Classes \/} report contains a list of these questionable descendant elements and tells what the descendant generation number vs.\ PENDING class generation number. \subsection{Reserved Pending Elements} The output report also contains a list of PENDING class elements that have been reserved since their insertion into the PENDING class. The user who has reserved the file is also listed. \section{Invoking the Show Merged Classes Tool} Use the following command to invoke the {\it Show Merged Classes \/} tool: \bigskip \begin{verbatim} $ SMC :== @DEVTOOLS:SMC.COM $ SMC [<``TABLE_ONLY''>] [<``ALL_PENDING''>] [<``ALL\_SPR''>] \end{verbatim} \bigskip $<$P-class-name$>$ is the name of the CMS library PENDING class, e.g. PENDING19.2. $<$S-class-name-list$>$ is one or more CMS library SPR class names separated by commas. For example, an S-class-name-list might look like this: {\sl SPR.12032, SPR.11001, SPR.02319\ \/} This parameter can also be @S-class-file, which is the name of an ASCII file that contains one SPR class name per line (150 is current limit of valid SPR classes for one report). An @S-class-file might look like: {\sl @disk\$bruno:[b192.default]192\_spr.com \/}. Using the @S-class-file approach is useful when there is a known set of SPRs to check a library PENDING class (or series of libraries) against. Finally, specifying the parameter ``USE\_CMS'' causes the tool to use the actual CMS library PENDING SubClass list generated as the SPR list. This last mechanism is useful particularly when the SPR classes in a CMS library are not known. $<$Cms-library-name$>$ is the name of the CMS library to search for the PENDING and SPR classes. For example, {\sl sogsdb\_load\_cms, \/} or {\sl disk\$hercules:[lib.oss.source.cms] \/}. This parameter can also be @Cms-names-file, which is the name of an ASCII file that contains one CMS library name per line. Each CMS library causes a different report to be generated. $<$Output-report-file$>$ is the name of the file where the {\it Show Merged Classes \/} report is to be printed. This will typically be SYS\$OUTPUT when you are running this tool from a batch command procedure. [$<$``TABLE\_ONLY''$>$] is an optional string ``TABLE\_ONLY'' that tells the tool not to generate the SubClass, Descendant Elements, or Reserved Elements lists, i.e. generate the Merged/Unmerged Elements table only. This can significantly speed up the processing time of the tool, particulary when the pending class has a large number of elements. [$<$``ALL\_PENDING''$>$] is an optional string ``ALL\_PENDING'' that tells the tool to print all of the PENDING elements whether they are merged or not. [$<$``ALL\_SPR''$>$] is an optional string ``ALL\_SPR'' that tells the tool to print all of the SPR elements whether they are merged or not. \subsection{Examples} Some sample invocations follow: {\small \$ SMC PENDING19.2 @disk\$bruno:[b192.default]192\_spr.com oss\_cms oss\_cms.smc\_report \$ SMC PENDING19.2 SPR.12345,SPR.01923 @cmslibs.com sys\$output ALL\_PENDING \$ SMC PENDING19.2 SPR.1* @cmslibs.com sys\$output ALL\_PENDING ALL\_SPR \$ SMC PENDING19.2 OSS\_CMS oss\_cms oss\_cms.smc\_report ALL\_SPR \$ SMC PENDING19.2 USE\_CMS oss\_cms oss\_cms.smc\_report TABLE\_ONLY \$ SMC PENDING19.2 @disk\$bruno:[b192.default]192\_spr.com @cmslibs.com oss\_cms.smc\_report } \clearpage \section{Sample Reports} This section lists some sample reports and follows each report with a summary of what the report reveals about the merged status of the library. \subsection{Sample Report 1} {\tt\footnotesize \begin{verbatim} -------- CMS SHOW MERGED CLASSES REPORT FOR LIBRARY: sogsdb_load_cms -------- Pending Class Name: pending19.2 SubClasses: SPR.12892 (*) SPR.12957 SPR.13429 Descendant Elements: QFOSMARTSTAR.LIS (4 vs. 2) QFVALUE.LIS (5 vs. 3) Reserved Elements: CGG0GF.DAT ROSE CGG1GK.DAT ROSE QFOSMARTSTAR.LIS WISSLER QFVALUE.LIS WISSLER -- Merged/Unmerged Elements Table -- Number of Number of Class Name Elements Unmerged Element Name Gen Number Status --------------------- ---------- --------- ------------------------- ---------- ------ PENDING19.2 8 3 LOAD_CGG0_GENERIC.COM 1 (E) LOAD_CGG1_KEYWORD.COM 3 (E) LOAD_CGG2_GRP_PAR.COM 1 (E) SPR.12502 3 3 CGG0GF.DAT 2 (G) CGG1GK.DAT 3 (G) CGG2GP.DAT 2 (G) SPR.12892 3 0 SPR.12894 2 2 CGG0GF.DAT 2 (G) CGG1GK.DAT 3 (G) SPR.12985 2 2 CGG0GF.DAT 2 (G) CGG1GK.DAT 3 (G) SPR.13429 2 0 ----------------------------------------------------------------------------------------------- \end{verbatim} } This {\it Show Merged Classes \/} report was generated using the command: {\small \begin{quote} \$ SMC PENDING19.2 @disk\$bruno:[b192.default]192\_spr.com sogsdb\_load\_cms sogsdb\_load.smc\_report \end{quote} } This report shows: \begin{enumerate} \item The PENDING class name is listed, in this case: {\sl PENDING19.2 \/}. \item All classes in the CMS library which have {\bf at least one \/} element that is also in the PENDING class are listed under the SubClasses section. This SubClasslist is generated independent of the disk\$bruno:[b192.default]192\_spr.com SPR list. In this case there are 3 SubClasses: SPR.12982, SPR.12957, SPR.13429. Note that SPR.12957 is not listed in the Merged/Unmerged Element table below which means that it was not specified in the disk\$bruno:[b192.default]192\_spr.com file. This can be seen by the (*) next to SPR.12957 in the SubClass list. \item The Descendant Elements list shows that there are 2 elements that are questionable in this library. For example, element QFOSMARTSTAR.LIS has generation 2 in the class PENDING19.2 and has already been modified twice bringing it up to version 4. This may or may not be a problem, regardless the information is given. \item There are 4 elements from class PENDING19.2 that have been reserved for modifications - two by user ROSE and two by user WISSLER. \item The first CMS class in the Merged/Unmerged Element Table is always the PENDING class. If there are any unmerged elements in this class, this means that they are not found in any SPR class in the library. For this example, there are 3 elements in the class PENDING19.2 that are not in SPR classes listed in disk\$bruno:[b192.default]192\_spr.com. This is a problem since anything in the PENDING class must be as the result of some SPR. \item Only those SPR classes from the file disk\$bruno:[b192.default]192\_spr.com that are in the CMS library sogsdb\_load\_cms appear in the Merged/Unmerged Element Table. These are listed alphabetically under the ``Class Name'' column of the Merged/Unmerged Element Table under the first class in the table which is the pending class. \item Those SPR classes that have 0 unmerged elements are in good shape - all of their elements were found in the PENDING class. The classes that are correct are SPR.12892 and SPR.13429. \item There are 3 SPR classes that do not have a clean element list, mainly because the generation numbers in the PENDING class are older that those in the SPR class. \item An element that is not found in the PENDING class will have an (E) under the status column. \item An element that is found in the PENDING class but whose generation number does not map will have a (G) under the status column. \end{enumerate} \clearpage \subsection{Sample Report 2} {\tt\footnotesize \begin{verbatim} -------- CMS SHOW MERGED CLASSES REPORT FOR LIBRARY: disk$hercules:[lib.imtool.dcl.cms] -------- Pending Class Name: pending19.2 SubClasses: SPR.13919 SPR.14060 Descendant Elements: Reserved Elements: -- Merged/Unmerged Elements Table -- Number of Number of Class Name Elements Unmerged Element Name Gen Number Status --------------------- ---------- --------- ------------------------- ---------- ------ PENDING19.2 16 0 IMTCOEF.COM 2 IMTTDB.IQL 5 LOADIMTPBA.COM 2 LOADIMTPCK.COM 2 LOADIMTPDT.COM 2 LOADIMTPEP.COM 2 LOADIMTPFP.COM 2 LOADIMTPGA.COM 2 LOADIMTPLP.COM 2 LOADIMTPMA.COM 2 LOADIMTPOD.COM 2 LOADIMTPQG.COM 2 LOADIMTPRG.COM 2 LOADIMTPWP.COM 3 LOADIMTPZG.COM 2 LOADPDB.COM 2 SPR.13919 1 0 SPR.14060 15 0 ----------------------------------------------------------------------------------------------- \end{verbatim} } This {\it Show Merged Classes \/} report was generated using the command: {\small \begin{quote} \$ SMC PENDING19.2 SPR.13919,SPR.14060 disk\$hercules:[lib.imtool.dcl.cms] imtool.smc\_report ALL\_PENDING \end{quote} } \clearpage This report shows a CMS library that is in ``good shape'', that is it is ideal to have all SPR class elements merged into the designated PENDING class: \begin{enumerate} \item There are no questionable descendants, no reserved elements, and no unexpected SubClasses. \item All elements in the two SPR classes are merged into the PENDING class. \item All elements in the PENDING class are also in one of the two SPR classes. \item The elements for class PENDING19.2 show in the Merged/Unmerged Elements Table because of the ``ALL\_PENDING'' parameter that was specified on the command line. Notice that when an element is merged and appears in the report, there are NO markings for it in the Status column. \end{enumerate} \clearpage \subsection{Sample Report 3} {\tt\footnotesize \begin{verbatim} -------- CMS SHOW MERGED CLASSES REPORT FOR LIBRARY: oss_cms -------- Pending Class Name: pending19.2 SubClasses: SPR.11749 SPR.11750 SPR.12098 SPR.12151 SPR.12666 SPR.12940 SPR.13018 SPR.13024 SPR.13033 SPR.13060 SPR.13203 SPR.13431 SPR.13455 SPR.13491 SPR.13506 SPR.13905 Descendant Elements: Reserved Elements: -- Merged/Unmerged Elements Table -- Number of Number of Class Name Elements Unmerged Element Name Gen Number Status --------------------- ---------- --------- ------------------------- ---------- ------ PENDING19.2 61 0 SPR.11749 2 0 SPR.11750 13 0 SPR.12098 2 1 OSSORT.FOR 4 (G) SPR.12151 1 0 SPR.12666 15 0 SPR.12940 3 0 SPR.13018 6 2 ORWFPD.FOR 3 (G) OSSORT.FOR 4 (G) SPR.13024 2 0 SPR.13033 8 2 ORFOSD.FOR 4 (G) OSRPKT.FOR 3 (G) SPR.13060 3 0 SPR.13203 4 0 SPR.13431 5 0 SPR.13455 1 0 SPR.13491 2 0 SPR.13506 2 0 SPR.13905 2 0 ----------------------------------------------------------------------------------------------- \end{verbatim} } \clearpage This {\it Show Merged Classes \/} report was generated using the command: {\small \begin{quote} \$ SMC PENDING19.2 USE\_CMS oss\_cms oss.smc\_report \end{quote} } This report shows: \begin{enumerate} \item There are no questionable descendant, reserved elements, or unexpected SubClasses. \item Since the USE\_CMS feature was used, the any SPR class in the SubClass list will also appear in the Merged/Unmerged Elements Table. \item The only potential problem with this library is that there are a few SPR elements that have different generations that the same elements in the PENDING class; for example, element OSSORT.FOR in SPR classes SPR.12098 and SPR.13010. Since OSSORT.FOR is not on the questionable descendants list, it means that the PENDING class element OSSORT.FOR must have a {\bf higher} generation number. Is this a problem - probably not since element OSSORT.FOR generaton number 4 descendant is not listed as an unmerged PENDING class element which means that the higher generation must be under one of the other SPRs in this table. Understand? \end{enumerate} \section{Generality} While this entire description of the {\it Show Merged Classes \/} tool has been geared towards the build environment here at STSI, the tool is written to work on {\bf ANY} CMS classes. It doesn't know the difference between a CMS class called PENDING19.2, SPR.12345, or BUCKET. Perhaps the command syntax should be generalized as such: \bigskip \begin{verbatim} $ SMC [<``ALL_PENDING''>] [<``ALL\_SPR''>] \end{verbatim} \section{Limitations/Quotas} The {\it Show Merged Classes \/}tool has the following limits which when exceeded, can cause unpredictable results. \begin{enumerate} \item {\bf MAX\_ELEMENTS \/}- The maximum number of elements per any one CMS class is 3000. \item {\bf MAX\_SUBCLASSES \/} - The maximum number of subclasses is 400. \item {\bf MAX\_SPR\_CLASSES \/} - The maximum number of SPR classes for one run is 150. \item {\bf ELEMENT\_NAMES \/} - The maximum length of an element name is 40. \end{enumerate} You may need to have your page file quota increased when you use the tol on CMS classes with large amounts of elements. \clearpage \section{About The Software} There are 6 files that are associated with this tool: \bigskip \begin{enumerate} \item {\it SMC.COM \/} This DCL procedure is the driver for the tool. It is responsible for parsing all command line arguments, particularly important for the @file parameters. It creates two datafiles for the main piece of software, {\it SHOW\_MERGED\_CLASSES.C (.EXE) \/}. One data file is created for the PENDING class data by executing a CMS SHOW CLASS/CONTENTS/OUT=some\_temp\_file some\_pending\_class. The second data file is created by issuing a similar command for each valid SPR class specified, concatenating all of the data into one file. It then calls the {\it SHOW\_MERGED\_CLASSES.C (.EXE) \/} which munches on the two data files to produce the output report. \item {\it SHOW\_MERGED\_CLASSES.C \/} This C program reads in the two class content data files and produces the output report. The Callable CMS interface is also used to generate the SubClass, Descendant Elements, and Reserved Elements lists. \item {\it WEED\_CLASSES.C \/} This C program is used when there is a file of SPR classes given as one of the parameters. It weeds out any SPR classes from the file that are not in the current CMS library in order to reduce processing time looking for unnecssary SPR classes in the DCL procedure. The Callable CMS interface is used to obtain the list of classes from the library for comparison to the file. \item {\it USE\_CMS.C \/} This C program generates a SubClass list file to be used as input to the DCL procedure as a file of SPR names. The Callable CMS interface is also used to generate this file. \item {\it SMC\_MESSAGES.MSG \/} This is a file of VMS type error messages to be printed via the sys\$putmsg system service utility. \item {\it SHOW\_MERGED\_CLASSES.MMS \/} This MMS file will rebuild (as necessary) the 3 executables: \begin{itemize} \item {\it SHOW\_MERGED\_CLASSES.EXE \/} \item {\it WEED\_CLASSES.EXE \/} \item {\it USE\_CMS.EXE \/} \end{itemize} \end{enumerate} \end{document}