From: Didier Morandi [Didier.Morandi@gmx.ch] Sent: Wednesday, June 20, 2001 12:22 PM To: Info-VAX@Mvb.Saic.Com Subject: PCSI_MENU: A draft spec (this post 380 lines long by 72 chars. Better read with courier 10) PCSI_MENU An application to learn and create installation packages with PCSI, or convert an existing OpenVMS VMSINSTAL installation procedure. ************************* Functional specifications ************************* Didier.Morandi (@gmx.ch) <-- please use this address for direct mail version 1.0-0 6-jun-2001 D Day: 57 years already! 1. General description ====================== The PCSI_MENU is an OpenVMS DCL command procedure and help file which provides three functions: a) CAI training on the COMPAQ OpenVMS PolyCenter(tm) Software Installation utility (PCSI) b) PCSI kit building c) conversion from OpenVMS KITINSTAL.COM procedures (used by the VMSINSTAL utility) to PCSI The CAI part is provided via explanation texts before and during each phase of a kit creation. The application allows verbose, brief or no help mode. The verbose mode will cause a detailed text to be displayed before each question, the brief mode will display a one line only text. A question mark at any time will display the verbose text, whatever mode has been selected at the beginning of a session via a customization menu. The PCSI kit building function is an interactive menu-driven process. The user has a set of items to select to build his/her kit. Help is provided according to the mode selected in the customization menu. For each item, a context sensitive sub-menu will offer advanced features. At the end of an item session, part of the PCSI code necessary to build a kit is generated. A truth table will ensure that no conflicts may occur from the choices of the user along the kit building session. The VMSINSTAL to PCSI conversion function is mainly an automated translation process similar to a compiler. But each time a PCSI function is not available for a given VMI$CALLBACK feature, a manual intervention from the user is flagged. At the end of the translation process, a global text analysis of the resulting PCSI decsription file is performed, then an interactive session is started during which some solutions will be suggested. These solutions come from the appendix A of the Polycenter Software Installation Utility Developer's Guide (document reference AA-Q28MC-TK dated january 1999 for OpenVMS version 7.2, or AA-Q28MD-TK dated April 2001 for OpenVMS 7.3). This document for OpenVMS 7.3 is available on-line from the COMPAQ OpenVMS documentation WEB site via the following URL: http://www.openvms.compaq.com:8000/73final/5952/5952PRO.html. Another document on PCSI, the OpenVMS System Manager's manual, may be useful to read. It is available too from the COMPAQ OpenVMS documentation WEB site at: http://www.openvms.compaq.com:8000/73final/6017/6017pro_006.html#use_pcsi Note: The PCSI utility is an integrated part of the COMPAQ OpenVMS operating system, introduced with OpenVMS version 6.1 in april/may (VAX/ALPHA) 1994. POLYCENTER was a trademark of Digital Equipment Corporation (today COMPAQ) used under license by COMPUTER ASSOCIATES (CA) for the following products bought from DEC by CA: Polycenter Accounting Chargeback (PAC), Console Manager (PCM), Performance Data Collector (PDC), Performance Advisor (PPA), Scheduler (PSCH) and System Watchdog (PSW). The PCSI_MENU application is a personal midnite freeware product 100% written by its author, without any commitment, support, warranty or quality control whatsoever from COMPAQ Computer Corporation. COMPAQ is in no way involved in its development and should not be contacted for any reasons about the PCSI_MENU application. The PCSI_MENU code will be free of distribution and use at the user's own risks. A kind of support forum will be provided at the following URL: http://groups.yahoo.com/group/vmsinstal. This software is (c) 2001 Didier Morandi, Zurich, Switzerland. 2. CAI training and the customization menu ========================================== The training, as said, is done via explanation texts and coherence controls. When starting a PCSI_MENU session, the following screen is displayed: [start of screen copy] * Please enter your first name: * Please enter your last name : [clear screen] Hello, welcome to PCSI Menu, version 1.0-0 on 19-may-2001 14:00:00 * Do you wish to access the customization menu? (Y/[N]/?) : (current defaults are: editor: EDT; HELP mode: VERBOSE, FRIENDLY) [end of screen copy] If the user wishes to enter his/her first and last name, the application will remember them for further use, and the welcome message will later read "Hello Ken, Welcome to..." In the customization menu, in addition to the help mode, the user may choose his/her favourite editor (for the moment only EDT and TPU are available), then "friendly" or "professional" dialog mode. The friendly mode will cause the program to say for example: "Okay, now I have all I need to build that kit for you. Do you want me to do it right now or do you wish to have a look at what I actually did from your answers? ([Build]/View) " The professional mode text would be instead: "Build or view kit? ([Build]/View) " Another training feature is the coherence control on the fly. When an option is asked to the user, it generates some embedded functional rules which are set to boolean values TRUE or FALSE. Then, if a mismatch answer is given later, the program will tell the user why the answer is invalid and use the context provided by the boolean rules values to give appropriate suggestions. Each time a PCSI feature or element is referred to in a help text, an URL will give a link to the corresponding page of the on-line documentation. Should the application be used via a DECwindows or emulator terminal, a simple CUT/PASTE will allow the user to have the given page instantly displayed to his/her terminal if the user's machine is connected to the Internet. Then, at the end of the kit build, eventual PCSI errors which occurred during the Product description File (PDF) processing are trapped and an explanatory text is displayed from the normal PCSI HELP file via the DCL command HELP/MESSAGE <pcsi_msg_id>. If VERBOSE mode is enabled, additional help is displayed after the PCSI HELP text, giving comments and other information on the meaning of the HELP text and corrective actions to perform (Note: This is a human interface choice from the author and does not mean in any way that the COMPAQ PCSI HELP text is insufficient or of bad quality). We also ask the user if s/he wants that we build a product_config.com for him/her. When the kit is built without errors, the user is then prompted to do a test installation on the system s/he is working on. Since one of the greatest features of PCSI is the REMOVE function, this function is explained in details to the user, to help him/her to decide to actually perform the test installation without fear (assuming the required OpenVMS privileges are available in the user's process, of course). During the test installation, the standard output device is redirected to a file to be scanned and analyzed later, should the installation fail. All test installations are done with the /LOG qualifier to help error management processing by the PCSI_MENU application. When the test is over, the DCL global symbol $STATUS is evaluated and the logfile is analyzed if the completion status is different from success. For each error or warning in the logfile, explanations are given to the user. The "inconsistent state" message is explained in details, then necessary actions may be performed automatically by the PCSI_MENU application to do a clean uninstallation, even if the previous installation didn't succeed (mainly by the use of an automatically generated "emergency" .PCSI$DESC file to actually perform a safe installation then do a REMOVE). Again, at any time, a question mark entered as a reply to a question will display the verbose help text. The help texts are in a regular OpenVMS help messages file, so a translation process for localization should be easy to perform. 3. The PCSI kit generator function ================================== When the user starts his/her session, a main menu is displayed with most of the "standard" PCSI functions which may be found in a .PCSI$DESC file. These functions are: a) prerequisites (mostly version checking) b) the pre configuration phase c) identifiers creation d) accounts creation e) directories and ACLs creation f) files copy and ACLs creation g) the post installation phase h) Installation Verification Procedure (IVP) i) messages to the system manager performing the installation For the pre and post installation phases, the user is prompted for an already existing DCL command procedure specification, if any, or an editing session is started after a long explanation text (VERBOSE mode only). For the identifiers, accounts, directories, files and ACL phases, a sub-menu is displayed to allow options to be added. The advantage of the menus and submenus is that code is automatically generated with the right syntax (well, we hope so :-) giving better chance to have the PDF file correctly built and then perform an error free installation. As far as files copy is concerned, the application actually asks the user where the files are located and the PDF code is generated automatically from a directory listing, preventing the user to do a long and boring session of questions/answers if there are numerous files to include in the kit (the last PCSI kit the author built for a Customer was 450'000 blocks big). The IVP may be included from an external procedure or automatically generated by the application. The Product Text File (PTF) is written by the user during an editing session once all messages entries have been included in the PDF. Then come the Release Notes, the Installation and User's Guide, and the Product Configuration Procedure editing sessions if PCSI_MENU detects that some of these documents are missing. The Release Notes file is created to be later extracted with the PRODUCT EXTRACT RELEASE_NOTES command. The Installation and User's Guide is mainly a pre-formatted file summarizing the OpenVMS documentation on PCSI installation. The Product Configuration Procedure is a template automatically built to help the user during the editing session (a kind of NET$CONFIGURE.COM but slightly shorter). 4. The VMSINSTAL to PCSI automatic translation function ======================================================= Foreword -------- This issue has been studied and discussed for ages since PCSI came to VMS land with OpenVMS 6.1. We do not want to give the impression that we have discovered something new. What we actually did has been a technical study of both utilities, then a careful study of appendix A of the PCSI Developper's Guide (for version 6 then version 7 of openVMS). After that, we have reached the point where we believe that, if one can do such translation by hand, as the author did a few months ago for a Customer, a piece of DCL code should help. Nothing else than that: HELP. So, how could we give such title to this chapter: "automatic translation function"? Well, the answer is in the code and here comes the spec. 4.1 The compiler philosophy --------------------------- If we add the KITINSTAL VMI$CALLBACK functions plus appendix A of the PCSI Developper's Guide plus some imagination, DCL knowledge and time, we come to what we call the "compiler philosophy" that we would like to word that way: a) if a VMI$CALLBACK has an equivalent in PCSI, let's generate the equivalent code b) if it has no equivalent, either the statement is mandatory for the installation or not c) if it is not, let's forget about its translation d) if it is, let's see if the code goes to the pre-configuration or the post-installation phase e) then we build the pre and post DCL command procedures from the KITINSTAL.COM code. By the way, we would like to suggest COMPAQ PCSI Engineering achitects to consider changing the name "pre-configuration" to "pre-installation" as it seems to be now accepted by everyone that PCSI does installations and no more installation plus configuration as VMSINSTAL does. PCSI may deliver a product_config.com file (not necessarily, but...), so the config is actually done after the installation. Hence, the expression "pre-configuration" is not correct. Back to the translation process. Here is the comment of the XXX$PRE_CONFIGURE.COM file written for the Customer we talked about previously: $!+ $! XXX$PRE_CONFIGURE.COM $! $! This procedure executes all KITINSTAL.COM commands which were previously $! executed before the VMI$CALLBACK PROVIDE FILE section. Functions handled $! by PCSI have been removed. Disks logical names selection has been removed $! because it is done once for all in the SYS$MANAGER:SYLOGICALS.COM procedure. $! The copy phase is done by PCSI. The post installation phase is done by a $! new procedure, XXX$POST_INSTALL.COM. The XXX_SYSTARTUP.COM generation $! has been removed as it's no longer dynamic, and thus the file is now part $! of the distribution kit. What do we see here? We have translation to corresponding PCSI statements, generation of a pre and post installation procedures, and that's it. Now, the next question is: what if we have a lack of information to do the exact translation? Answer: We ASK the user. Et voila. This leads to point number 4.2. 4.2 With a little help from my friend ------------------------------------- Experience and Usenet newsgroup chats have demonstrated that there is no way to split a KITINSTAL.COM file in three, build the pre-configuration procedure with part one, the .PCSI$DESC file with part two and the post-installation procedure with part three. Why? because the KITINSTAL procedure is a DCL program, doing what a program does: GOSUB, GOTO, IF THEN ELSE, symbol substitution and so on. So, our approach has been (modestly) a kind of AI (Artificial Intelligence) approach. We scan the KITINSTAL text and we try to figure out what can be converted to pre and post procedures. If the scan gives no answers or fuzzy logic (I hate this expression :-) we ask the user. After a few "stupid" questions from the PCSI_MENU program, the user will understand the philosophy of the pre and post procedures and will edit them, forgetting - maybe without notice - that the identifiers and account creation, directories and ACL creation and files copy were already removed from his/her code. Never forget that the user will be probably the author of the KITINSTAL. S/he knows it better than we do, better than the best "PCSI compiler" we have written within the PCSI_MENU procedure does. So, let's use his/her knowledge, let's (try to) be humble and efficient, and let's ask the user about what are his/her preferred choices in terms of coding. So, where is the automatic process in all this? It is in the fact that we lead the user to ask him/herself the good questions to produce the code that we technically cannot produce by ourselves via DCL. The automatic process has three aspects: o build code o train the user to "think different" o produce a valid PCSI kit Why is it automatic? Because should errors occur during the PRODUCT PACKAGE command or during the PRODUCT INSTALL command, we take back the control of the process and we explain where are the errors, how to correct them, then we restart the session until the kit installs without errors. This is much better than just reading the doc, isn't it? 4.3 The "automatic" product_config.com procedure ------------------------------------------------ The scan of the KITINSTAL.COM file is simple, because all VMI$CALLBACK instructions are easily identified. Once they have been processed, we may find some logical names definition and even dynamic code generation. All this can be parsed to produce a configuration file. This is what we do. Remember, at the beginning of a session, we ask the user if s/he wants that we produce a product_config.com file. If we do, then an editing session will allow the user to change what has to be changed, then comes a ^Z and the configuration file is there. To summarize, we believe that the VMSINSTAL to PCSI evolution should be done that way: I. separate installation and configuration II. train the user to the PCSI philosophy III. build code that can be edited later It is well known that it is much easier to modify a somewhat wrong existing code than starting from scratch. 5. Evolution ============ tbs [end of version 1.0-1] (also posted in http://groups.yahoo.com/group/vmsinstal)