PAGESWAPPER Preview of the Spring 1984 Symposium Jeffrey S. Jalbert, VAX Systems SIG Symposium Coordinator Jack D. Cundiff, VAX Systems SIG Assistant Symposium Coordinator We want to take this opportunity to invite you to the 1984 Spring Symposium in Cincinnati, Ohio, June 4 - 8, 1984. The Symposium is always an exciting week and this spring will be no exception. In fact, several presentations have been added to make it even better than ever. For a beginning, the VAX System Sig and Digital are co-sponsoring a short course on VAX Cluster Management Saturday June 2, 1984 from 9 AM to 5 PM. This course will have a large enrollment and we are planning for over 400 persons to attend. Materials will be provided for all attendees. This course was designed by the Pros, the developers themselves, and will be taught by them. The seminar will discuss special VAX cluster design, implementation, performance and system management issues. Among the components covered will be: * Internals of the HSC intelligent disk controller * Cluster Interconnect (CI) performance under VMS, specifically, various SCS mechanisms at the core of all cluster data and message transfers PAGESWAPPER - April 1984 - Volume 5 Number 10 Preview of the Spring 1984 Symposium * Design and implementation of the connection manager, which defines and maintains a consistent, global cluster state * Design and implementation of the distributed file system * Design and implementation of the distributed job controller * Details of designing and installing a VAXcluster from a system (cluster) management prespective. A cookbook approach towards setting up your own VAXcluster. For those of you interested in pre-symposium seminars on Sunday June 3, 1984, the Sig is sponsoring 3 sessions. The first is LISP and AI Programming Techniques Tutorial. This tutorial is designed for persons who would like to learn LISP on their own but need a foundation. Topics to be covered include: * LISP approach to data representation * Basic LISP fuctions and what they do * How one approaches problems in LISP * Some simple techniques common in LISP and AI programming * Suggested approaches to self education in LISP The second is VAX Performance Monitoring which has been a tremendous success at the last two symposium. The emphasis of this seminar is on the methodology of VAX Performance Monitoring. This seminar will be aimed at anyone responsible for system availability, tuning, performance, planning and scheduling. The third is VAX System Management for the New System Manager. This seminar is designed for the new VAX System Manager or for those wanting to become familar with a VAX. Topics to be covered include: * site preparation once the VAX is on order * who is reponsible for what during installation 2 PAGESWAPPER - April 1984 - Volume 5 Number 10 Preview of the Spring 1984 Symposium * what to do after the Digital installers leave * how to set up user accounts * some software aids for the new system manager Once we have gotten you over the weekend, plan for a full week of VAX sessions and related VAX sessions. The streams for these sessions will follow. Just some of the highlights are the Advanced System Question and Answer Session scheduled again on Friday afternoon. But this time it will be followed by a VAX cocktail party and celebration. There are many sessions on VAX/VMS 4.0 including performance and enhancements as well as MicroVAX, VAXELN, hardware and new security features. Later in this issue is a list of the VAX sessions by day. Limitation on Scope of VAX Symposium Handouts March 26, 1984 Dear VAX SIG Members, With the current development committments we have, it will not be possible for VMS to submit handouts for Spring Symposium. Our plate is completely full between now and DECUS. Would it be possible to inform your potential buyers of the publication that there will be no VMS engineering input as part of this handout? I will however, commit to print handouts for the pre-symposium VAX cluster short course. Sincerely, Trevor Kempsell 3 PAGESWAPPER - April 1984 - Volume 5 Number 10 In this issue... In this issue... Preview of the Spring 1984 Symposium . . . . . . . . 1 Limitation on Scope of VAX Symposium Handouts . . . 3 In this issue... . . . . . . . . . . . . . . . . . . 4 Editor's Workfile . . . . . . . . . . . . . . . . . 5 Corrections to March 1984 Pageswapper . . . . . . . 6 Europe Symposium Zurich 1983 Q & A PARTY . . . . . 11 Using VMSINSTAL with User-Written Applications . . 17 VAX Sessions at the Spring 1984 Symposium . . . . 72 Eagles and Egg on Your Face . . . . . . . . . . . 75 INPUT/OUTPUT . . . . . . . . . . . . . . . . . . . 77 LUG Agenda . . . . . . . . . . . . . . . . . . . . 82 VAX System SIG Committee List . . . . . . . . . . 83 INPUT/OUTPUT Submission Form . . . . . . . . . . . 86 System Improvement Request Submission Form . . . . 88 General material for publication in the Pageswapper should be sent (US mail only -- no "express" services please) to: Larry Kilgallen, PAGESWAPPER Editor Box 81, MIT Station Cambridge, MA 02139-0901 USA Preference is given to material submitted as machine-readable text (best is Runoff source). Please do not submit program source, as that is better distributed on the VAX SIG tape. Material for "The DBMS Monitor" section of the Pageswapper (pertaining to VAX-11 DBMS) should be sent to: Julie Llewellyn United Technologies Microelectronics Center 1365 Garden of the Gods Road Colorado Springs, CO 80907 USA Change of address, reports of non-receipt, and other circulation correspondence should be sent to: DECUS U.S. Chapter, MRO2-1/C11 Attention: Publications Department One Iron Way Marlborough, MA 01752 USA Only if discrepancies of the mailing system are reported can they be analyzed and corrected. 4 PAGESWAPPER - April 1984 - Volume 5 Number 10 Editor's Workfile Editor's Workfile by Larry Kilgallen, Pageswapper Editor Once again at the Spring Symposium in Cincinnati, those attending will be able to submit short notes and comments to the Pageswapper by sending mail on the demonstration machines to the name PAGESWAPPER and in addition, your comments regarding the VAX Systems SIG tape can be submitted by sending mail on the demonstration machines to the name VAXTAPE J. L. Prather sent along a copy of an SPR he submitted suggesting that DEC software product installation be done in two phases. The initial phase would involve copying the data from floppies or TU58s and could be done with users logged on. Looking at what Richard L. Aurbach of Monsanto Company has discerned from the VMSINSTAL.COM shown at Las Vegas (see article entitled "Using VMSINSTAL with User-Written Applications" later in this issue), that might just be possible in the future. It is not clear whether that advance copy facility will be documented or supported. If nobody in your LUG has mentioned it, be advised that the new VMS Internals and Data Structures manual is now out. I mean really out; ordinary civilians have them - they are not still making their way through the DEC Press version of SDC. I bought one at the local DEC bookstore and someone else from my LUG got hers in the mail from the order cards that were available in Las Vegas. Things are really changing in the Pageswapper editing business with contributions which overflow our page limit. Deferred until next month is The Westinghouse Report, a review of the Las Vegas Symposium put together by Al Sorrell and Marty Adkins. In his cover letter, Al explains that the late release date is caused by the necessity of getting various corporate approvals at Westinghouse. So for those of you who are going to the Cincinnati Symposium, a Las Vegas report in the May Pageswapper may be too late. Those of you who are not going to Cincinnati and did not go to Las Vegas, however, can carry the May issue in to your boss as part of the explanation of what you are missing. 5 PAGESWAPPER - April 1984 - Volume 5 Number 10 Corrections to March 1984 Pageswapper Corrections to March 1984 Pageswapper by Larry Kilgallen, Pageswapper Editor Well, it's like this; I was changing the RUNOFF flags I use and managed to remove all plus signs (+) from the March Pageswapper. Here are the most glaring problems caused by the error; a corrected Pageswapper will be on the Spring 1984 SIG Tape. Allocate UBA Map Registers in the same 32K Unibus Address Space Page 2 ************ the first UBA map register number (CRB$L_INTD+VEC$W_MAPREG) and total number of UBA map registers (CRB$L_INTD+VEC$B_NUMREG). ****** the first UBA map register number (CRB$L_INTDVEC$W_MAPREG) and total number of UBA map registers (CRB$L_INTDVEC$B_NUMREG). The ************ ************ register number (CRB$L_INTD+VEC$W_MAPREG) and total number of UBA map registers (CRB$L_INTD+VEC$B_NUMREG). ****** register number (CRB$L_INTDVEC$W_MAPREG) and total number of UBA map registers (CRB$L_INTDVEC$B_NUMREG). ************ Page 4 ************ ; fields CRB$L_INTD+VEC$W_MAPREG and ; CRB$L_INTD+VEC$B_NUMREG specifies the UBA map ; registers allocated. A zero in R0 means failure. ; In this case, CRB fields CRB$L_INTD+VEC$W_MAPREG ; and CRB$L_INTD+VEC$B_NUMREG contain zeros. ;-- ****** ; fields CRB$L_INTDVEC$W_MAPREG and ; CRB$L_INTDVEC$B_NUMREG specifies the UBA map ; registers allocated. A zero in R0 means failure. ; In this case, CRB fields CRB$L_INTDVEC$W_MAPREG ; and CRB$L_INTDVEC$B_NUMREG contain zeros. ;-- ************ 6 PAGESWAPPER - April 1984 - Volume 5 Number 10 Corrections to March 1984 Pageswapper Page 5 ************ MOVZWL CRB$L_INTD+VEC$W_MAPREG(R8),R2; ;Get the first map reg # MOVZBL CRB$L_INTD+VEC$B_NUMREG(R8),R1; ;Get total # of map registers ****** MOVZWL CRB$L_INTDVEC$W_MAPREG(R8),R2; ;Get the first map reg # MOVZBL CRB$L_INTDVEC$B_NUMREG(R8),R1; ;Get total # of map registers ************ ************ MOVZWL CRB$L_INTD+VEC$W_MAPREG(R8),R10; ;Save the first map reg # MOVZBL CRB$L_INTD+VEC$B_NUMREG(R8),R11; ;Save total # of map registers ****** MOVZWL CRB$L_INTDVEC$W_MAPREG(R8),R10; ;Save the first map reg # MOVZBL CRB$L_INTDVEC$B_NUMREG(R8),R11; ;Save total # of map registers ************ ************ MOVW CRB$L_INTD+VEC$W_MAPREG(R8),- ;Save the first map TEMP_MAPREG[R7] ; register # MOVZWL CRB$L_INTD+VEC$W_MAPREG(R8),R2;Get the 1st map reg ;# of the first sub-extent ****** MOVW CRB$L_INTDVEC$W_MAPREG(R8),- ;Save the first map TEMP_MAPREG[R7] ; register # MOVZWL CRB$L_INTDVEC$W_MAPREG(R8),R2;Get the 1st map reg ;# of the first sub-extent ************ ************ MOVZBL CRB$L_INTD+VEC$B_NUMREG(R8),R2;Get total of map reg SUBL R1,R2 ;Get total # of map reg. of ****** MOVZBL CRB$L_INTDVEC$B_NUMREG(R8),R2;Get total of map reg SUBL R1,R2 ;Get total # of map reg. of ************ ************ MOVW R0,CRB$L_INTD+VEC$W_MAPREG(R8);Save the first ;map register #. MOVB R2,CRB$L_INTD+VEC$B_NUMREG(R8);Save total # of ****** MOVW R0,CRB$L_INTDVEC$W_MAPREG(R8);Save the first ;map register #. 7 PAGESWAPPER - April 1984 - Volume 5 Number 10 Corrections to March 1984 Pageswapper MOVB R2,CRB$L_INTDVEC$B_NUMREG(R8);Save total # of ;map registers. ************ Page 6 ************ ************ CRB$L_INTD+VEC$W_MAPREG(R8);register # MOVB TEMP_NUMREG[R0],- ;Save total # of CRB$L_INTD+VEC$B_NUMREG(R8);map registers JSB G^IOC$RELMAPREG ;Release map registers ****** CRB$L_INTDVEC$W_MAPREG(R8);register # MOVB TEMP_NUMREG[R0],- ;Save total # of CRB$L_INTDVEC$B_NUMREG(R8);map registers JSB G^IOC$RELMAPREG ;Release map registers ************ ************ CLRW CRB$L_INTD+VEC$W_MAPREG(R8);Clear CRB fields CLRB CRB$L_INTD+VEC$B_NUMREG(R8);(Same) ; ****** CLRW CRB$L_INTDVEC$W_MAPREG(R8);Clear CRB fields CLRB CRB$L_INTDVEC$B_NUMREG(R8);(Same) ; ************ ************ CRB$L_INTD+VEC$W_MAPREG(R8);register # MOVB R11,- ;Restore total # of map CRB$L_INTD+VEC$B_NUMREG(R8);registers. ****** CRB$L_INTDVEC$W_MAPREG(R8);register # MOVB R11,- ;Restore total # of map CRB$L_INTDVEC$B_NUMREG(R8);registers. ************ RMS I/O for Improved Fortran I/O Performance Page 19 ************ I = I + 1 IF ( RECORD(I:I) .EQ. CHAR(9) ) THEN J = (( I + 7 ) / 8 ) * 8 K = J - I + 1 8 PAGESWAPPER - April 1984 - Volume 5 Number 10 Corrections to March 1984 Pageswapper L = LENGTH + K - 1 RECORD(I:L) = BLANK(1:K) // 1 RECORD(I+1:LENGTH) LENGTH = L ****** I = I 1 IF ( RECORD(I:I) .EQ. CHAR(9) ) THEN J = (( I 7 ) / 8 ) * 8 K = J - I 1 L = LENGTH K - 1 RECORD(I:L) = BLANK(1:K) // 1 RECORD(I1:LENGTH) LENGTH = L ************ Page 21 ************ I = I + 1 IF ( RECORD(I:I) .EQ. CHAR(9) ) THEN J = (( I + 7 ) / 8 ) * 8 K = J - I + 1 L = LENGTH + K - 1 RECORD(I:L) = BLANK(1:K) // 1 RECORD(I+1:LENGTH) LENGTH = L ****** I = I 1 IF ( RECORD(I:I) .EQ. CHAR(9) ) THEN J = (( I 7 ) / 8 ) * 8 K = J - I 1 L = LENGTH K - 1 RECORD(I:L) = BLANK(1:K) // 1 RECORD(I1:LENGTH) LENGTH = L ************ Comparison of Three Versions of RUNOFF Page 46 ************ .DEFINE COMMAND/SECTION/S2.LM+5.RM-5.C; ****** .DEFINE COMMAND/SECTION/S2.LM5.RM-5.C; ************ 9 PAGESWAPPER - April 1984 - Volume 5 Number 10 Corrections to March 1984 Pageswapper Page 47 ************ {A+B}/{C+D}+X ****** {AB}/{CD}X ************ Page 55 ************ .RIGHT [JUSTIFY][[+-]n];text ****** .RIGHT [JUSTIFY][[-]n];text ************ INPUT/OUTPUT # 255 Page 79 ************ simply divide your baud rate by 10 (8 bits in 1 byte + 1 start bit and 1 stop bit). Hence, 1200 baud becomes 120 characters of data per second. The UNIBUS is ****** simply divide your baud rate by 10 (8 bits in 1 byte 1 start bit and 1 stop bit). Hence, 1200 baud becomes 120 characters of data per second. The UNIBUS is ************ ************ the order of 8Mbytes +) of 1.2 Mbytes, it is possible to calculate the total number of interrupts that can ****** the order of 8Mbytes ) of 1.2 Mbytes, it is possible to calculate the total number of interrupts that can ************ Page 81 ************ more. This means that even though you may have 64 + terminals hooked up at 1200 baud, you will NOT be 10 PAGESWAPPER - April 1984 - Volume 5 Number 10 Corrections to March 1984 Pageswapper ****** more. This means that even though you may have 64 terminals hooked up at 1200 baud, you will NOT be ************ Europe Symposium Zurich 1983 Q & A Party by Michael Rotert, FakultaT Fur Informatik " " Universitat Karlsruhe, Rechnerabteilung " D-75 Karlsruhe 1, Postfach 6380, Germany This session was logged by giving each questioner a sheet of paper and asking him to return it with both question and answer written on it. Unfortunately not all papers were returned and some were written by "non-English" speaking delegates. Some answers have been altered to translate the sense of the question. Unfortunately, on this session the panel was biased towards product-line management rather than technically oriented. Q. Will DCL have structured elements (e.g. GOSUB) or other enhancements like speed increase? A. GOSUB is under consideration together with other structuring elements. Speed increase will probably not be seen. Q. We have an 11/780 with a UDA50/RA81 on a separate Unibus (i.e. with nothing else on it). DEC wanted to install it with the 6.2 ms strap in place (comment please). A. Not answered. Q. From curves published it is apparent that the bandwidth attainable with the UDA is limited to ca. 650 KBytes/s. This seems to coincide with competitors' (E...) claiming that DEC is unable to use the full Unibus bandwidth... (every second cycle only). Why is this so and will the situation be improved upon? A. Not answered. Q. What's the purpose and status of SYSGEN-param UDABURSTRATE? A. Not answered (Author: there were a lot of discussions around these points). 11 PAGESWAPPER - April 1984 - Volume 5 Number 10 Europe Symposium Zurich 1983 Q & A Party Q. When will a run-time licence be available for DBMS? A. No answer yet. Q. Pascal compiler produces environment attribute records only when variables are shared via an environment file. It does it not, however, when only constants, types or procedure declarations are shared. Feature or bug? Suggestion: Compilation switch and module attribute to enable/disable generation of environment attribute records. A. Write an SPR. Q. FMS: When will it be possible to translate the FMS run-time errors which appear at the bottom line of the screen? A. We will investigate it in the next release. Q. Monitor: When will there be a monitor function to monitor the IO usage per disk, i.e. number of IO's, average length of the IO's, reads/writes, cache hits? A. There is a program in development and when enough people want it, it will be distributed. Q. In one of the introductory talks, three ways were shown of how to hook terminals to a VAX-cluster. All of them involved logging in on a particular node. I do not care on which node of the cluster I log in. I want to log in on the cluster, it should decide itself on which node I am placed, preferably the one with the least work. A. Reasonable request, we have thought about it. Q. PHONE may call you when you are running RTPAD (set host to another node). It is necessary to find out on which node you are called. A. PHONE tells you on which node it is calling you. Suggestion: Call forward automatically by PHONE, or reject calls when running RTPAD and tell the caller on which node he may call you. Q. When will backup support disk to tape backups over DECNET? A. Problem with mounting remote magtape (no MOUNT/SYSTEM for tape). Q. It is possible to mount the remote tape via a command file on the remote node. The command file is invoked via "TASK=filename" in the backup command. Backup could write to the tape, but not perform the rewind. 12 PAGESWAPPER - April 1984 - Volume 5 Number 10 Europe Symposium Zurich 1983 Q & A Party A. BACKUP doesn't know it's working with a tape. Would not be too difficult to implement. Q. Is there any way for a driver to force deassignment of the channels assigned to it? A. No. Q. Any significant changes to device driver environment for Version 4? Can I specify an extended IRP myself? A. There is some space at the end of an IRP. There may be a symbol for end of IRP and one could use that to access free space. Q. Any possibility of making drivers more than 1 psect? A. No. Q. Could some kind of incremental loading of shareable images be made available? A. Noted down. Q. DEBUG - Is there a possibility to get a full dump only if a run time error occurs? A. We are working on it. Q. Can someone describe means of accessing memory/processes in a cluster VAX from another node, e.g. MBX/EFNs? What do you use if not DECNET? A. Use DECNET or Lock Manager. Nothing else is supported initially. Q. Does image accounting work for all images or just for VMS images? A. Yes, for all images. Q. What are time files? SYSBOOT-F-BOOT system time files are in too many noncontiguous pieces. A. No answer (Author: Lots of discussions and some funny suggestions). Q. DCL editor: Will the /line command still be editable? A. No longer. Q. Will error messages for quotas and privileges be displayed with the the description of the missing privilege or short quota? 13 PAGESWAPPER - April 1984 - Volume 5 Number 10 Europe Symposium Zurich 1983 Q & A Party A. Will come eventually. Q. Can the question for date/time on boot be suppressed when no battery backups for the time of year clock is present? A. Yes, there is a SYSGEN parameter, read chapter 12 (System Management)! Q. LP. would like each print job to start with . A. Not possible yet, probably in next version. Q. Can batch queues have an owner, and how do I determine a job's current batch queue? A. It is not possible to create a batch queue with owner. The name of the current batch queue is not accessible in an easy way. Q. Operator reply to request is put onto job log, it should be put also into a DCL variable. A. Noted down. Q. We want to log a symbolic traceback + date&time stamp only to SYS$ERROR and not to SYS$OUTPUT. Is or will it be possible to call the traceback handler from a higher level condition handler? A. Suggestion not considered before. Q. Sort routines. - The program callable SORT routines, unlike the DCL SORT statement, try to obtain 7 * WSEXTENT in virtual address space and this causes considerable problems with processes which are using large WSEXTENTs, to make the best use of shared global code. Will this be fixed soon? A. In the next major release of VMS (V4?). Q. Messages. - Shared images from messages - /COPY won't work. A. You cannot make shared images from shared images created with message modules. Q. The volume labels of multi-volume tape files must be sequential, e.g. ABC001, ABC002, ABC003, ... . Accepting any labels, in any order, would be useful. A. Major changes to MOUNT command in version 4.0 but it is not known whether this is included. Perhaps more definite answer in 'Pageswapper' (Ok, guys where is it?). 14 PAGESWAPPER - April 1984 - Volume 5 Number 10 Europe Symposium Zurich 1983 Q & A Party Q. The RUN command for a detached process often does not produce an error log (.ERR file). Why? This is for a process that runs from a terminal process. A. Image accounting may give an indication. Alternatively create a termination mailbox which will receive the termination accounting record. My suggestion is that the documentation should tell you this but that there should be a clearer indication. Q. LIB$SPAWN. - You can set input and output when spawning a process. How can you set the error file? Will a change be made to SPAWN to handle this? A. You don't! Loginout sets error file to output file. Q. Is it foreseen that a power-fail will preserve status so that the system will continue BATCH jobs that were running at power-fail? A. Version 4.0 has a checkpoint feature so that batch jobs can be restarted after interruptions. Q. Are there plans for a V3 System Internal Manual? A. Yes - via Digital Press. (See Pageswapper page 5) Q. Can I build a do-it-yourself LP spooler? A. New logic for spooling in V4 should be documented in V4. Q. What is the max size of a UAF file? A. Only normal ISAM file limit. Q. How do I change the max size of the global/local symbol table? A. SYSGEN parameter. Q. Real software support once a year is ok. In the U.K. I only get software support 9:00 - 17:00. I need 24 hour support. Can I continue to call the States until it is offered? A. (The panel preferred not to comment.) Q. When will file archiving be properly supported under VMS? A. No current plans but the need is identified. Q. Can I use BACKUP to backup files from a remote RSX node? 15 PAGESWAPPER - April 1984 - Volume 5 Number 10 Europe Symposium Zurich 1983 Q & A Party A. No, not any remote node, and not in the future ("that we know of"). Q. System 780 with RM80 system disk. - After long down time, rebooting the system gives error message: "Cannot find boot file". Booting from other disk and copy VMB.EXE to the RM80 cures this. A. Send SPR. Q. Why did it only take 5 years to write chapter 12 of S.M.O.G.? A. A lot of work and experience was required to produce it! Q. Spooler should be able to - back N pages; - take a checkpoint and requeue the job for continuation. A. Noted down. Q. With a straightforward FORTRAN source file the LINE NUMBER of the error is the line number for EDT. An include statement includes every line in the "include" and it is no longer true. Anything possible? A. No. Q. Backup in V3.3 - Will not start a backup volume set on a tape which has been previously used as a continuation tape for a previous backup. A. New behaviour for /NOREWIND. Use /INIT on BACKUP. Q. Can I install a shareable image with (W:RE)? A. Yes. Q. Is multi-volume COPY possible? A. Yes. Q. Are there plans to enhance security at login time (multiple attempts)? A. Yes. Q. How to restore a disk on a 730 with RL02 (System), R80 (User), with no tape drive but with access via DECNET to 780 with a tape drive? A. No reply on log. 16 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications Using VMSINSTAL with User-Written Applications Richard L. Aurbach Monsanto Company 800 N. Lindbergh Blvd. St. Louis, MO 63167 (314)-694-5453 January 10, 1984 Abstract The VMSINSTAL procedure is used by DEC to install system software. By properly understanding how it works, you can use it to install your user-written software applications as well. Caveat While I believe that this report accurately describes the VMSINSTAL procedure in VAX/VMS V3.4, neither I nor Monsanto Company can be held responsible for any inaccuracies. Appendix A includes a discussion of changes to VMSINSTAL for V4.0 of VMS. This information is based on an examination of the VMSINSTAL file from the pre-field-test version (X28J) of VMS which was exhibited at the fall '83 DECUS Symposium. Of course, it is impossible for anyone other than the VMS Developers to do more than speculate on the details. 17 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications Introduction to VMSINSTAL DEC uses VMSINSTAL to install new releases of their software. You can use it to install your software, also. It is clear from reading VMSINSTAL.COM that a great deal of work went into making it a general and flexible software installation tool. As such, it should be as useful for you as it is for DEC. The only problem is figuring out how to use it -- i.e. how to build an installation kit which VMSINSTAL will be able to install on your system. Here, we attempt to describe how the procedure works and how to build a kit so that you can use VMSINSTAL to install your software. You should already be familiar with Chapter 4 of the Software Installation Guide in the VMS documentation set. Benefits There are several benefits to using VMSINSTAL. First, every package which uses it is installed in basically the same way. The installation is easy and straight-forward. Many software packages have long and complex installation instructions (not yours, of course!); with VMSINSTAL the instructions can be short and simple. All of the complexity is hidden from the installer. Second, the installation procedure handles a wide variety of installation media (including DECnet from another node!) and works the same on all VAX processors. The detailor/retailor sequences for a dual-RL02 VAX-11/730 system are handled automatically. By using the kit, a single effort to develop an installation procedure should work correctly on a wide variety of configurations. Third, the installation procedure is designed to handle minor annoyances (such as having insufficient disk space on the target system or having the system crash in the middle of the installation) in a fairly clean way. Lastly, if you decide to use VMSINSTAL, you will probably decide to read it. This has proven to be an extremely useful learning experience, since there are a number of interesting and clever ideas to be found in it. It may make you a better DCL programmer. 18 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications Overview While later chapters will go into gruesome detail, the basic operation of VMSINSTAL is simple. The installation kit consists of one or more BACKUP savesets (one saveset is required). The procedure creates a working directory (which I refer to as the installation directory) which is a subdirectory of [SYSUPD]. It then backs up the (first) saveset into this directory and executes a command file which is found on the saveset. This file does all the work. When done, the installation directory is deleted from the system disk. Product Name The program name (up to 6 characters) and the product version number are combined into a product name. This is described in the Software Installation Guide. As an example, version 2.0 of Datatrieve has the product name DTR020. This is a magic name for VMSINSTAL. For one thing, this will be the name of the subdirectory of [SYSUPD] used as the installation directory. For another, the (first) saveset of the installation kit will have a saveset name of "product-name.A". For example, the installation kit for Datatrieve version 2.0 consists of three savesets -- named DTR020.A, DTR020.B, and DTR020.C. KITINSTAL.COM The main saveset ("product.A") must contain a file called KITINSTAL.COM. The format of this file is highly conventional. KITINSTAL is the controller for the installation -- it does all the application-specific portions of the installation. Building an installation kit consists of writing KITINSTAL.COM based on the requirements of the application, collecting all the needed files together, and creating the required saveset. The thrust of this paper is to describe how to write KITINSTAL for your application -- what things to include and what is done for you by VMSINSTAL. 19 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications Control Flow The basic control flow of VMSINSTAL is - Set up needed symbols and logicals. All symbols and logicals begin with "vmi$". Validate the parameters specified in the invocation of the procedure. Check the specified installation device for validity. Determine the set of products to be installed. - If the system is disk-poor (such as a dual-RL02 11/730), detailor the system. - Initialize the marker file (described later). Start the statistics demon if specified. Set up auto-answer processing if specified. Set up callback tracing if specified. Initialize the defer file (described later). - Restore the primary backup saveset for the product. - Call KITINSTAL to install the product. - Perform all defer-file activities (described later). - If specified, call KITINSTAL to perform the Installation Verification Procedure. - Clean up the installation directory. Stop the Statistics Demon if it was running. Close all miscellaneous files and clean things up. - If detailoring activities were performed earlier, retailor the system. - If specified as part of the installation procedure, reboot the system. Two concepts were introduced above which will be described in detail later -- the marker file and the defer file. The marker file is used to aid in recovery of the system in the event of a system crash. It lets the system know what was going on when the crash took place. The defer file is used to provide some safety during an installation, also as an assist to crash protection. Most important operations are set up by KITINSTAL, but are not done until later. This makes sure that an error will not leave the system in an intermediate state. 20 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications Undocumented Features of VMSINSTAL Like all good DEC products, VMSINSTAL contains a number of undocumented features which are of interest to someone developing an installation kit. Installation Media The kit may be supplied on any medium from which BACKUP can restore a saveset. Therefore, a disk file on a mounted volume, a "sequential disk" medium (such as floppy disks), a magtape, or a remote saveset (via DECnet) can all be used as installation media. Undocumented Options The OPTIONS parameter of the VMSINSTAL procedure can be used to do a number of interesting things, only a few of which are documented. The list is as follows: * A -- Auto-Answer File This option is documented in the System Installation Guide. * B -- Booting This is used as part of the crash-recovery procedure. If the system crashes during an installation, VMSINSTAL is invoked with the "B" option as part of system restart (in STARTUP.COM). You probably don't need to worry about this feature -- it's just here for completeness. * C -- Callback Trace This is an exceptionally useful feature for a developer. It generates a file ([SYSUPD]"product".CBT) which contains a trace of all VMSINSTAL callback routines. You can think of this as a trace of all subroutine calls -- it provides a record of what was done during the procedure. * D -- Debug Switch This option turns on a debug feature. The most important thing it does is to prevent rebooting of the system when an application requires it. Otherwise, it 21 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications isn't too useful. * K -- Kit Debug Switch This option sets a switch which may be used for debugging KITINSTAL. Its usefulness depends on how you write KITINSTAL. * L -- Log Switch This is a documented option. It is used to cause all invocations of APPEND, BACKUP, COPY, CREATE, DELETE, LIBRARY, PURGE, RENAME, SEARCH, and UNLOCK to log what they do. The result is that your console record of the installation contains a lot of useful information about what was done to your system. * Q -- Quality Assurance This one is a mystery. This option doesn't seem to do much, other than enable certain messages to appear on your console record of the installation. * R -- Alternate Root This documented option allows the installation to be done in an alternate root. This can be very useful in a testing environment -- when you want to try out something new without burning your bridges behind you. * S -- Statistics Selecting this option enables something called the Statistics Demon. This is a command procedure which runs as a subprocess to this installation process. It compiles all sorts of useful statistics about what happened during the installation. The most useful statistics concern disk use. The statistics demon will tell you the peak disk usage and the final disk usage of your installation -- very useful pieces of data to include in instructions to the installer. The data is put in a file ([SYSUPD]"product".ANL). I always use options C, L, and S when using VMSINSTAL. The combination gives a very complete picture of what was done. This is useful to me, both as a developer of a new procedure and as a system manager who cares what has been done to my system. 22 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications VMSINSTAL Concepts This chapter discusses some of the ideas around which the VMSINSTAL procedure is built. Basic Techniques This section will describe some of the basis for how VMSINSTAL works and what a release must look like if VMSINSTAL is to process it correctly. Release Kit Identification In Chapter 4 of the System Installation Guide, the naming convention by which each release kit is identified is explained. For example, the version V3.3 upgrade to VMS is called VMS033, version V2.0 of Datatrieve is identified as DTR020, etc. The symbol "vmi$product" is equated to this name. Installation Directory The VMSINSTAL procedure needs somewhere to store the files which make up the installation kit while it is performing the installation. This should be a unique area (i.e. a special purpose subdirectory), to eliminate any potential problems with file name conflicts. VMSINSTAL creates a subdirectory of SYS$UPDATE to hold the installation kit. This subdirectory is deleted when the installation is completed. The name of the subdirectory is the product name. In this paper, this subdirectory is referred to as the Installation Directory. VMSINSTAL defines the symbol "vmi$kwd" (the kit working directory) to be its device/directory specification. In this paper, the rest of the system disk is called the System Area. 23 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications Callback Routines One of the most interesting techniques used in VMSINSTAL is the concept of a callback routine. A callback routine is essentially a subroutine. That is, it is a section of command procedure which begins with a label (the subroutine name) and ends with an EXIT directive. Inputs to the callback routine may be symbols or logicals defined at the time of invocation. The routine may define a GLOBAL symbol or a process logical name on output and may also return status. Invocation of these callback routines is accomplished by recursively calling VMSINSTAL from within VMSINSTAL! The routine maintains a first-time-called flag ("vmi$installing") which tells it whether to interpret the first parameter as a subroutine name or not. This flag is a local symbol, so that it disappears when VMSINSTAL exits. If the flag exists and is set, then the P1 parameter is interpreted as a subroutine name, and control is dispatched to the appropriate piece of the command procedure with a GOTO. Kit Organization VMSINSTAL makes a number of assumptions about the structure of the release kit which it uses to install the product. You MUST follow these conventions if your installation procedure is to work correctly. Backup Savesets A VMSINSTAL release kit contains one or more BACKUP savesets. All of the savesets must be accessed using the same installation device. The installation kit may reside on console media, a magtape, a sequential disk, a particular directory of a non-foreign disk, or on a remote system (using DECnet). The file name of each saveset MUST be the product name of the product being installed. For example, the file name of the backup saveset for VMS V3.3 is VMS033. The file type of the first backup saveset must be A. If there are additional savesets (which is legal but not required), then their file types must be B, C, etc. 24 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The backup savesets must contain all of the files required to perform the installation. In particular, the saveset whose file type is "A" must contain a file named "KITINSTAL.COM". KITINSTAL.COM The file KITINSTAL.COM is the master control file for the installation. That is, it contains all of the product-specific portions of the installation procedure. Details on how to write a KITINSTAL.COM procedure are presented in Chapter 6 of this paper. Basically, the KITINSTAL.COM procedure calls VMSINSTAL callback routines to perform the required installation steps. KITINSTAL is called twice -- once during installation and once to perform the Installation Verification Procedure (IVP). When calling KITINSTAL to perform the installation, the P1 parameter is "VMI$_INSTALL". When called to execute the IVP, the P1 parameter is "VMI$_IVP". In addition, the P2 parameter is a boolean which indicates whether the "K" option was specified in the invocation of VMSINSTAL. Callback Tracing Since callback subroutines are such a vital aspect of VMSINSTAL, it is useful to trace the flow of control through them. The Callback Trace option is provided for this purpose. To use callback tracing, you must specify "OPTIONS C" when you invoke VMSINSTAL. This causes a file to be built in [SYSUPD] which lists the callback routines used. The report is [SYSUPD]"product".CBT. Statistics Demon While the "OPTIONS L" logging feature will provide a lot of information about what happened in an installation, it may not tell you everything you want to know. To provide more information, the Statistics Demon was devised. The Statistics Demon is a subprocess which is created by VMSINSTAL if "OPTIONS S" is specified. This subprocess monitors disk use and maintains statistics. What actually happens is that a special callback routine (STATISTICS_DEMON) is run. This 25 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications routine initializes itself and then monitors the system disk until told to stop by the main process which is running VMSINSTAL. The routine then produces a report which includes the following information. - Disk Usage Including initial, minimum, maximum, and final free-block counts, the peak disk utilization during the installation, and the net disk utilization. - Files Added A list of all files added to the system by the installation. - Files Deleted A list of all files deleted from the system by the installation. - Files Modified A list of all files which were modified by the installation. - Files Accessed A list of all files (except for installed program images) which were accessed during the installation. If this information is of interest to you, you should use the Statistics Demon. The Statistics Demon creates the report file [SYSUPD]"product".ANL. Protection from Installation Failure There are a variety of ways in which an installation of a software product could fail and leave your system in an undesirable state. Were such a thing to happen, considerable effort would be required to fix up your system, returning it to its pre-installation state. VMSINSTAL will attempt to protect you from such an occurrence. 26 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications Safety Mode VMSINSTAL attempts to protect you from installation failure by executing in two phases. In the first phase, checks are performed to see if all of the necessary operations performed by the installation will succeed. If it can be determined that all operations will succeed, then the operations are actually performed in the second phase. This approach is called "Safety Mode". Safety mode can require a higher peak disk utilization than would occur if every operation were performed immediately. Therefore, it is normal to check to see if there is sufficient space on the disk to install the product in Safety Mode. If insufficient space is available, each operation is performed immediately. Deferred Processing Safety mode operates by deferring processing of commands which can effect your system. For example, moving a file from the installation directory to the system area is deferred, since your system could be left in a compromised state if some files were moved, but others were not (due to an installation failure). Updates to files (such as patches) are normally done by moving a copy of the file to be updated to the installation directory, making the update, and then setting things up so that moving the file back to the system area is deferred until later. Library updates, however, are made immediately. The reason for this is that the installation process may itself depend on a library being updated. 27 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The Defer File The mechanism by which operations are deferred is the Defer File. This is a file, created by VMSINSTAL in Safety Mode, which contains a list of operations to be performed. The callback routines for critical operations work in different ways depending on whether Safety Mode is on. If it is on, they perform checks and then write a command line to the defer file. If it is off, they implement the command. Once the basic installation processing is finished, the defer file is closed, safety mode is turned off, and the defer file is executed. This causes each of these callback routines to be executed again. Since safety mode is now off, the operations occur immediately. When you see the message "Files will now be moved to their target directories..." on your console during an installation, this means that KITINSTAL has finished and the deferred operations are about to begin. Protection from System Crashes It may happen that the system will crash during an installation. VMSINSTAL attempts to handle this problem and recover as gracefully as possible under the circumstances. The Marker File The heart of the crash protection is the Marker File. This file is created by VMSINSTAL and is used to store information about what it is doing. The VMSINSTAL procedure updates the marker file at various times during its processing to indicate what it was doing. Since the marker file is only open while being updated, only a small window exists in which a system crash will leave the marker file in an erroneous state. The UPDATE_LIBRARY callback routine is a routine which uses the marker file to keep track of what it is doing. This is important because updating a library is not a deferred action. This routine performs the following steps. 28 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications - It opens the marker file, updates it to indicate that a library is being updated, and closes the marker file. - It updates the library. - It opens the marker file, updates it to indicate that the update is complete, and closes the marker file. In this way, if the system crashes while the library is being updated, the system has a way of notifying you that the current copy of the library is suspect. Crash Recovery If the system crashes during an installation, then a copy of the marker file exists on the system. The site-independent startup file [SYSEXE]STARTUP.COM checks to see if this file exists and performs appropriate actions if it does. Therefore, crash recovery involves cooperation between the VMSINSTAL procedure and the STARTUP procedure. If the marker file exists, STARTUP invokes VMSINSTAL with the special option "OPTIONS B" (for booting). VMSINSTAL recognizes this special option and transfers control to code which examines the marker file to determine what it was doing when the system crashed. In some cases, VMSINSTAL will suggest that the installation be restarted from the beginning. In other cases, VMSINSTAL will be able to determine that the processing has progressed to the point where it may be continued from its current point. In this case, VMSINSTAL will continue processing. Finally, there will be cases in which VMSINSTAL will be in an intermediate state, in which various recovery procedures must be applied. In this latter case, the procedure will tell you what to do. VMSINSTAL always asks you if you are satified with the backup of your system disk before proceeding with the installation. One of the reasons for asking this question is that there are phases of VMSINSTAL in which crash recovery requires manual intervention. In these cases, a reliable backup is essential. 29 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications VMSINSTAL Control Flow In this chapter, the flow of VMSINSTAL is summarized. This will, in turn, help make clear which functions need to be provided by KITINSTAL and which functions are already provided for you by VMSINSTAL. The VMSINSTAL flow is divided into a series of steps. STEP_1 This is the initialization step. Logicals and symbols are defined. The system checks to make sure that you are running from the SYSTEM account, that you have sufficient privilege for the installation, and that your quotas are adequate. It also checks to see if you are running stand-alone and warns you if you are not. Finally, it makes sure you are satisfied with the backup of your system disk. If STARTUP.COM invoked VMSINSTAL with "OPTIONS B" (booting), STEP_1 transfers control to the crash-recovery step (STEP_12). STEP_2 This step determines what the distribution device is and validates that a legal choice has been specified. If the console is specified, then the console is connected (via SYSGEN), the console volume is dismounted (if it is mounted), and the console device is allocated. A flag is set to remind VMSINSTAL to remount the console volume when it is done. 30 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications STEP_3 This step determines the list of products to be installed. If appropriate, it asks you to place the first distribution volume on the distribution device and mounts the device. It then checks to see if the required savesets exist on the distribution medium to perform the requested installations. STEP_4 If the system device is small (i.e. a VAX-11/730 with dual RL02's), then this step undoes system tailoring and prepares the system for the update. STEP_5 This step is a loop point. It finds the next product to be installed and creates and initializes the marker file as is appropriate to reflect this installation. If there are no more products in the list, it transfers control to STEP_3 to see if there are other kits to install. STEP_6 This step cleans up [SYSUPD] preparatory to performing the installation. If "OPTIONS S" was specified, it starts up the Statistics Demon. If "OPTIONS A" was specified, it determines whether an auto-answer file already exists. This enables it to set things up so that the auto-answer file may either be used (if it exists) or created (if it does not). If "OPTIONS C" was specified, the callback tracing feature is turned on. The installation directory is created and the defer file is opened. Finally, several installation-specific symbols are initialized, so that their settings do not carry over from one installation to another in a multi-product installation sequence. 31 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications STEP_7 This step restores the saveset for the product to be installed. It validates that KITINSTAL.COM exists in the saveset. STEP_8 This step invokes KITINSTAL.COM, passing the value "VMI$_INSTALL" as parameter P1. This causes KITINSTAL to install the product. STEP_9 This step uses the defer file to implement the deferred processing which may have been specified by KITINSTAL. STEP_10 If a startup procedure was defined for the product (using a SET STARTUP command, then the startup procedure is invoked. This is assumed to establish the environment needed for an Installation Verification Procedure. The IVP is then executed (if requested) by invoking KITINSTAL.COM with the value "VMI$_IVP" as parameter P1. STEP_11 At this point, the installation of the product has been completed. If the Statistics Demon is running, it is told to finish up and produce its report. The marker file is deleted. If the system does not need to be rebooted at this point, control is transferred to STEP_5 to process the next kit. Otherwise, normal cleanup is performed. 32 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications STEP_12 This step is invoked if the system crashed during installation. The Marker File is examined to determine what needs to be done. Appropriate messages are printed and recovery, if possible, is attempted. Normal Completion Normal completion includes closing and deleting files created by the procedure, re-establishing your system tailoring environment (if tailoring was undone earlier), remounting the console device if necessary, and restoring your saved UIC and default directory. If this product requires that the system be rebooted, then [SYSEXE]SHUTDOWN.COM is invoked to shut down and reboot the system. VMSINSTAL Special Symbols The following list describes useful VMSINSTAL symbols and logical names. Some are primarily interesting to understanding how VMSINSTAL works. Others will be extremely useful when you are building a VMSINSTAL procedure of your own. vmi$callback Local symbol. Equated to "@SYS$UPDATE:VMSINSTAL". Used to invoke a VMSINSTAL subroutine (otherwise known as a callback routine). 33 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications vmi$defer_file Process logical name. This symbol defines the "defer file", vmi$kwd:vmidefer.com. vmi$device Local symbol. Equated to the device name of the distribution volume. vmi$find Local symbol. Equated to "@SYS$UPDATE:VMSINSTAL FIND_FILE". Used to invoke the FIND_FILE subroutine. vmi$free_blocks Local symbol. The number of free blocks available on the vmi$root device. vmi$ivp Global boolean symbol. If true, an Installation Verification Procedure should be executed. Initial value is false. 34 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications vmi$kwd Process logical name. The kit working directory created to hold the installation files. In the case of installation of FOOXYZ version 2.1 in the standard root, for example, vmi$kwd would have the value SYS$SYSROOT:[SYSUPD.FOOXYZ021]. In this paper, vmi$kwd is referred to as the "Installation Directory". The rest of the system disk (in particular the rest of the specified root) is referred to as the "System Area". vmi$msg Local symbol. Equated to "@SYS$UPDATE:VMSINSTAL MESSAGE VMSINSTAL". Used to invoke the MESSAGE subroutine for a VMSINSTAL error message. vmi$no_error Local symbol. Equated to "DEFINE/USER SYS$ERROR NL:". Used to turn off error messages for a single DCL command. vmi$no_output Local symbol. Equated to "DEFINE/USER SYS$OUTPUT NL:". Used to turn off output messages for a single DCL command. 35 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications vmi$place Global symbol. The distribution volume. Typical values might be CSA1: (for the console floppy), MFA0: (for a magtape), or a fully-qualified file specification, for a saveset file located on disk. vmi$pretty Local symbol. Equated to the name of the product being installed. However, the format of vmi$pretty makes it appropriate to use this symbol when issuing messages to the user. For FOOXYZ version 2.1, this symbol has the value "FOOXYZ V2.1". vmi$product Local symbol. Equated to the name of the product being installed. For example, if installing FOOXYZ version 2.1, this symbol has the value "FOOXYZ021". vmi$purge Global boolean symbol. If true, files should be purged when moved. That is, old copies of files which were replaced during the installation should be deleted. Initial value is true. 36 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications vmi$reboot Global boolean symbol. If true, the nature of the installation requires that the system be rebooted on completion of the installation. This will happen automatically (i.e. the VMSINSTAL procedure will invoke SYS$SYSTEM:SHUTDOWN.COM). Initial value is false. vmi$remote Local boolean symbol. If true, the distribution volume is located on a remote node. vmi$remount Local boolean symbol. If true, then the distribution device must be remounted when VMSINSTAL is done. This symbol is set true for console devices and for disk devices which are mounted /FOREIGN. vmi$root Process logical name. Value is the root directory to use. Unless OPTIONS R is specified, this symbol has the value SYS$SYSROOT. vmi$safety Global boolean symbol. If true, then the procedure is executing in safety mode. Initial value is true. It is the responsibility of KITINSTAL to determine if there is enough disk space on the system disk to operate in safety mode. 37 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications vmi$startup Global symbol. This symbol contains the name of an application startup command procedure. This procedure is executed for an Installation Verification Procedure. Typically, this is the procedure which is included in the SYSTARTUP.COM procedure after installation. vmi$_failure Local symbol. Used to signal unsuccessful completion. Equated to %X10F50000. vmi$_success Local symbol. Used to signal successful completion. Equated to %X10F50001. vmi$_unsupported Local symbol. Used to signal an unsuccessful completion due to an attempt to exercise an unsupported feature. Equated to %X10F50008. VMSINSTAL Subroutines Using the VMSINSTAL call-back procedure is conceptually similar to calling subroutines. These routines are called with a set of arguments to perform specified actions. Some return status indications of success or failure, others return arguments indicating what they did, some do both. 38 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The following lists all of the VMSINSTAL subroutines which are available to the developer of a new procedure. Several routines (which are clearly intended for the internal use of VMSINSTAL and which would not be useful in any other context) are ignored [1]. ASK The ASK subroutine is used to prompt the user for a response, read the response, and evaluate it. It provides a uniform user interface, handles data type checking and default values, and responds to a ? with help. The routine also supports an auto-answer file. It will read the response from a previously created auto-answer file, or write the user's response to a new auto-answer file, depending on the auto-answer option that is appropriate. All questions to the user should be handled using the ASK routine. The routine is invoked by VMI$CALLBACK ASK value prompt default type help "value" is a global symbol whose value is the user's response. The symbol is numeric for integer or boolean data types and is a string for the string data type. The "prompt" parameter is the prompt string. It should not include any indication of the default value (if any). Nor should it end with a : or ?. These will be added by the routine. The "default" parameter is the optional default value. If a default is specified, it will be displayed as part of the prompt string (in square brackets). A response will use the default value. If no default is specified (parameter is ""), then a value must be specified. In this case, a response will cause it to redisplay the prompt. --------------------- [1] The MOUNT_LIBRARY_DISK, PLACE_VOLUME, REMOUNT_CONSOLE, DETAILOR, and RETAILOR routines are only used to configure and reconfigure 11/730 systems in the 2-RL02 environment. OPEN_REPORT_FILE is used when creating the output reports for either callback tracing (OPTIONS C) or statistics (OPTIONS S). STATISTICS_DEMON is the routine which is executed as a subprocess to compile the statistics information for OPTIONS S. 39 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The "type" parameter is an OPTIONS-type parameter. Legal values are "R", "B", "I", "H", and "S". o If "R" is specified, the bell will be rung before the prompt is displayed. o If "B" is specified, a boolean result is requested. Legal responses are Y, YE, YES, N, and NO. The result is checked for one of these values and the user is re-prompted if the response is not correct. o If "I" is specified, an integer response is requested. The result is checked for a valid integer response and the user is re-prompted if an integer is not supplied. o If "H" is specified, the help message is displayed before the prompt is issued. o If "S" is specified (or if neither "B" or "I" is specified), then a string response is requested. The "help" parameter specifies the help message. This parameter is optional. If the parameter is not specified, then typing a ? in response to the prompt will cause the message "Sorry, no help available." to be printed. There are two legal formats for the help message. If "help" contains a string, that text is used as a help message. If the first character of the "help" string is @, however, then it is interpreted as a command file which is executed to provides the help information. This latter technique is useful if a multi-line help message is desired. For example, the command VMI$CALLBACK ASK DIGIT "Enter a number" 3 I "Type a digit" will cause the prompt * Enter a number [3]: to appear. Typing a ? will cause the help message "Type a digit" to appear, followed by the prompt once again. A will return the integer value 3 in global symbol DIGIT. Typing a number will return that value. If the characters typed do not represent a valid integer, the message "Please enter an integer value." will appear and the user will be re-prompted. If OPTIONS A was specified and there is no auto-answer file, the entry will be recorded in a new auto-answer file. If OPTIONS A was specified and an auto-answer file already exists, it will be used for the response. This this latter case, both the prompt and the response will be echoed on the user's terminal. 40 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The routine will return vmi$_success unless there is a problem with the auto-answer file. The prompt is stored in the auto-answer file and compared against the current prompt. If they do not match, then the auto-answer file is out of synchronization with the sequence of questions. In this case, a fatal error is signalled. CHECK_NET_UTILIZATION The CHECK_NET_UTILIZATION subroutine determines whether there is sufficient disk space available on the vmi$root device for the installation of the application. This is a NET utilization of disk space. The installation will require a peak utilization which is higher and which is handled by the SET SAFETY subroutine. The routine is invoked by VMI$CALLBACK CHECK_NET_UTILIZATION result blocks "result" is a global boolean symbol which is returned by the routine. It has the value true (1) if there is sufficient space for the installation and false (0) otherwise. "blocks" is the number of net disk blocks required by the software being installed. It should be an integer value. For example, VMI$CALLBACK CHECK_NET_UTILIZATION OK 1000 will return OK = 1 if at least 1000 blocks are available on the vmi$root device. The routine always returns vmi$_success. CHECK_VMS_VERSION The CHECK_VMS_VERSION routine is used to determine if the proper version of VMS is currently installed. For example, if a product requires V3.2 or later for correct operation, this routine could be used to find out if the proper version of VMS is in use. 41 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The calling sequence is VMI$CALLBACK CHECK_VMS_VERSION result version test "result" is a boolean global symbol. It is given the value "true" (=1) if the current VMS version is equal to or higher than the specified version level, and "false" (=0) otherwise. "version" is the minimum acceptable version. The format is nnm where "nn" is the major version level and "m" is the minor version number. The major version must be two characters long, so use a leading zero until VMS V10.0 comes along. For version V3.2, code "032". The "test" parameter is used for internal version numbers which appear to be associated with internal testing. It is only used if F$GETSYI("VERSION") returns a value which does not begin with a "V". It should apply only to DEC internal use, and should not be a concern elsewhere. The routine always returns vmi$_success. CONTROL_Y This routine is used to trap CNTL/Y's typed during the execution of a command procedure. It issues a fatal error message and returns status of vmi$_failure. It is called without arguments. CREATE_ACCOUNT This routine is used to create a new account on the system. The routine defines both SYSUAF and NETUAF, so that it is possible to define both system and network proxy accounts using this facility. The routine is called by VMI$CALLBACK CREATE_ACCOUNT name switches The "name" parameter is the account's userid (i.e. the value entered in response to the LOGIN Username: prompt). 42 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The "switches" parameter is the set of AUTHORIZE switches used to define the account, such as /DEVICE, /DIRECTORY, etc. The routine returns vmi$_success unless it cannot find the file VMI$ROOT:[SYSEXE]SYSUAF.DAT (the SYSAUF file). CREATE_DIRECTORY This routine is used to create a new directory on the system. There are two flavors of this command, one for creating system directories and one for creating user directories. The difference between them is that a system directory is always created on vmi$root -- that is, it is always a rooted directory, and hence the device name is not specified. The calling sequence depends on whether a system or user directory is being created. System Directory Creation The calling sequence for a system directory is VMI$CALLBACK CREATE_DIRECTORY SYSTEM name switches "name" is the name of the directory being created. Note that in this case, the brackets which are part of the directory-name syntax are not used. That is, to create vmi$root:[foobar], issue the command VMI$CALLBACK CREATE_DIRECTORY SYSTEM FOOBAR. The "switches" parameter defines any switches which may be applied to the CREATE/DIRECTORY command, such as /OWNER_UIC, etc. If the name of the directory begins with "SYS", an appropriate message is printed. 43 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications User Directory Creation The calling sequence for a user directory is VMI$CALLBACK CREATE_DIRECTORY USER name switches The "name" parameter is the device/directory specification for the directory to be created. To create directory USER$DISK:[foo], issue the command VMI$CALLBACK CREATE_DIRECTORY USER USER$DISK:[FOO]. The "switches" parameter defines any switches which may be applied to the CREATE/DIRECTORY command, such as /OWNER_UIC, etc. If the device name specified in P3 is the same as the vms$root value, then an appropriate message is printed. The routine always returns vmi$_success. DELETE_FILE This routine deletes a system file. If called while in safety mode, the routine writes the DELETE_FILE command to the defer-file, so that it can be executed later (assuming everything goes well). If called in unsafe mode, the file is actually deleted. When deleting the file, all versions are deleted. The routine is called by VMI$CALLBACK DELETE_FILE filespec "filespec" is the file name of the file to be deleted. It should be a fully qualified file name, since the defaults applied to missing fields in the name are not useful. The routine checks to see if the file exists. If it exists, then the routine returns vmi$_success always. If the file does not exist, however, the procedure returns vmi$_failure. 44 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications FIND_FILE The FIND_FILE subroutine is used to search for the existence of a file. It returns a logical name equated to the file specification if the file is found. This routine is used so frequently, that the symbol vmi$find has been defined as VMI$FIND := 'VMI$CALLBACK FIND_FILE The routine is invoked by VMI$FIND found filespec default option result "found" is a return value. It is a process logical name whose value is the file specification of the file, if found. If the file is not found, then the logical name is deassigned. "filespec" is the file specification of the file which is to be found. "default" is the default file specification for the file to be found. Normally, the device/directory specification for the file is placed here. The "option" parameter determines how the file search is done. Legal values are "W", "S", and "E". o If "W" is specified, the initial file search is made in the installation directory. o If "S" is specified, then the area specified by the "filespec" (as augmented by "default") is searched. In a tailoring environment, the lib$sysroot library disk volume is searched also, if needed. NOTE If both "W" and "S" are specified, then the installation directory is searched FIRST. The system area is not searched unless the file is not found in the installation directory. o If "E" is specified, then an error message will be printed if the file is not found. 45 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications "result" is an optional return value. If specified, the "result" global symbol will have the value "W", "S", or "E" on return, depending on the result of the find operation. The exception is the case of a find-error with no "E" specified in "option". In this case, the "result" is returned null. That is, "result" is set to "W" if the file was found in the installation directory, "S" if the file was found in the system, and "E" if a file-not-found message was printed. Otherwise, "result" is blank. If the file is found, the routine exits with status "vmi$_success". If the file is not found, but no error message was called for, then the routine also exits with status "vmi$_success". If an error message is printed, then the routine exits with status "vmi$_failure". GET_SYSTEM_PARAMETER This routine is used to check the current value of a SYSGEN parameter. It does this by running the SYSGEN image. The routine is called by VMI$CALLBACK GET_SYSTEM_PARAMETER result parameter "result" is a global symbol in which the value of the SYSGEN parameter is returned. "parameter" is the name of the SYSGEN parameter. For example, to find out what the current value of VIRTUALPAGECNT is, use the command VMI$CALLBACK GET_SYSTEM_PARAMETER VPG VIRTUALPAGECNT. On return, the global symbol VPG will contain the virtual page count parameter value. The routine will return vmi$_success for any valid SYSGEN parameter. If the P3 value specified is not a valid SYSGEN parameter, it will return vmi$_failure. 46 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications MESSAGE The MESSAGE routine is used to issue a message to the console from which the VMSINSTAL procedure is run. There are two formats of the command, depending on whether the facility is VMSINSTAL or the product being installed. Message is from VMSINSTAL In this case, the format of the command is either VMI$CALLBACK MESSAGE VMSINSTAL severity code text or VMI$MSG severity code text "severity" is the severity code (W,S,E,I, or F). "code" is the message code name. "text" is the text of the error message. This form of the routine will generate a message of the form %VMSINSTAL-"severity"-"code", "text" Message is from the Product In this case, the format of the command is VMI$CALLBACK MESSAGE severity code text The parameters have the same meaning as above. The facility name used in this case is the name of the product being installed. For example, if installing product FOO, this routine will generate the message %FOO-"severity"-"code", "text" 47 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The routine will return vmi$_success, unless the severity code of the message is F (fatal). If the message is fatal, then the routine will exit with status code %X10F50004. MOVE_FILE The MOVE_FILE subroutine is used to transfer a file from the installation directory to the appropriate system directory. In safety mode, the routine records the appropriate command line in the "defer file" for later execution. If not in safety mode, the file is moved immediately from the installation directory to its target location. Movement of the file is via a RENAME operation if the source and destination device names are the same and via BACKUP/NEW_VERSION/OWNER=ORIGINAL otherwise. The routine will purge the destination directory of the old version of the file if desired and will optionally install the new version of the file (INSTALL /REPLACE) if requested. The routine is invoked by VMI$CALLBACK MOVE_FILE result filespec options "result" is a return argument. It is a process logical name whose value is the destination file specification. "filespec" is the fully qualified file specification of the file to be moved. It is assumed that the specification includes the destination device and directory. The file with the specified name is moved from vmi$kwd to this location. Legal values for "options" are "R" and "K". o If "R" is specified, the file will be reinstalled after being moved. o If "K" is specified, then the destination directory will not be purged of the old copies of this file, even if general purging was requested. As an example, the command VMI$CALLBACK MOVE_FILE VMI$EXE VMI$ROOT:[SYSEXE]FOOBAR.EXE R will move the file VMI$KWD:FOOBAR.EXE to VMI$ROOT:[SYSEXE]FOOBAR.EXE. The file will be re-installed and will be purged if vmi$purge is true. 48 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications If the operation is successful, vmi$_success is returned. The logical symbol "result" will be defined. In safety mode, its value will be the source file (in the installation directory). In the unsafe mode, its value will be the destination file. If the file is not found in the installation directory, then vmi$_failure is returned. "result" is undefined in this case. If a reinstall operation is requested which fails, a fatal error is signalled. PATCH_IMAGE This routine is used to provide a patch for an existing image. It is assumed that a patch input file exists which contains the correct set of commands to incorporate the patch into the image. The operation of this routine is fairly complicated. First, the routine looks up the patch command file in the installation directory to make sure it exists. Then it checks to see if you included the name of the image file to be patched in the calling sequence. If the image file specification was not included in the calling sequence, then the routine assumes that the information may be found in the first line of the patch command file. In this case, the patch command file is opened and the first record is read. The format of the first record of the patch command file must be !filespec options where "filespec" is the name of the file to be patched. It must immediately follow the initial comment delimiter. The "options" parameter is optional and may take the values "I","R", "K", and/or "J". The "I" value means that the image is a sharable image in IMAGELIB.OLB, which must also be updated after the patch. The "R" value means that the image should be re-installed. The "K" value means that the old versions of the image should be kept. The "J" value means that a journal file should be generated documenting the changes made to the image. If the image file is specified in the calling sequence, then the routine does not look at the first line of the patch command file at all. It is assumed that the options desired are specified in the options parameter in the calling sequence. The options parameter is then tested to see if "J" (Journaling) is specified. If it is, then the system checks to see if there is already a journal file in existence. If so, then the 49 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications journalling information will be appended. Next, the image is patched. The output image from the PATCH utility is written to the installation directory. If this is the first patch to this image (i.e. when finding the image file, it is found in the system area, but not in the installation directory), then a PROVIDE_IMAGE command is generated to copy the result back to the system area. If, on the other hand, the image file was found in the installation directory, then this is assumed to mean that another patch has already been applied. Therefore, the previous patch command issued the PROVIDE_IMAGE command in safety mode, so it need not be done again. Finally, if journalling caused a new journal file to be created, a PROVIDE_FILE command is generated to store the journal in the system area. The complications in this command arise because it may be necessary to patch the same image more than once. The procedure attempts to make sure that unnecessary operations are not performed. The net result is clearcut, however. The PATCH utility is invoked to apply a patch command file to the specified image, which is then returned to the system area. The calling sequence is VMI$CALLBACK PATCH_IMAGE result patchfile filespec options "result" is a process logical symbol. On output, it is the name of the image file patched. "patchfile" is the name of the patch command file to be used. This file is located in the installation directory. "filespec" is the name of the file to be patched. If this parameter is blank, then the first line of the patch command file is assumed to contain the information (as described above). Legal values of "options" are "J", "I", "K", and "R". o If "J" is specified, then a patch journal will be created. o If "I" is specified, then the image is part of SYS$LIBRARY:IMAGELIB.OLB and will be replaced in this library when the patch is complete. o If "R" is specified, then the image will be re-installed when it is moved back to the system area. o If "K" is specified, then old copies of the image in the system area will be kept, even if purging was requested. 50 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The routine will return vmi$_success except if one of the following errors occur: * The patch command file is not found in the installation directory. * The image file is not found. * A previous journal file is found in the system area, but the UPDATE_FILE command which attempts to retrieve it failed somehow. * The PROVIDE_IMAGE call to store the patched image in the system area failed. PRINT_FILE This routine causes a file to be printed on device SYS$PRINT. The print job will be given a jobname which is the same as the product name. The command allows multiple copies of the file to be printed. The calling sequence is VMI$CALLBACK PRINT_FILE filespec copies "filespec" is the file specification of the file to be printed. "copies" is the number of copies desired. If omitted, one copy will be printed. The routine attempts to find the file before issuing a PRINT command. If the find fails, vms$_failure is returned. Otherwise, the routine returns vmi$_success. PROVIDE_DCL_COMMAND This routine is used to update the system DCL tables to provide a new command to the system. The routine creates an updated version of DCLTABLES.EXE in the installation directory and then copies it back to the system using a PROVIDE_IMAGE command. This latter command normally executes in safety mode, so the actual update is not made until the end of the installation process. If the installation directory already contained a copy of DCLTABLES.EXE (for example, due to a previous PROVIDE_DCL_COMMAND call in safety mode), then the file is NOT copied back to the system, since it is assumed that another 51 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications command will take care of this. Therefore, multiple calls to this routine will cause only a single copy of DCLTABLES.EXE to be moved back to the system area. In addition, the process DCL tables are also updated so that the current process can execute the new DCL command. This is needed for the Installation Verification Procedure (IVP). The routine is called by VMI$CALLBACK PROVIDE_DCL_COMMAND filespec "filespec" is the file specification of the .CLD file which is the input to the SET COMMAND command. The routine returns vmi$_success unless the CLD file is not found, the DCLTABLES.EXE file is not found, or the PROVIDE_IMAGE routine fails. PROVIDE_DCL_HELP This routine is used to update the system help library with a new help file. The procedure invokes UPDATE_LIBRARY for SYS$HELP:HELPLIB.HLB. The library update operation is "REPLACE", so a previous version of the help information will be replaced with the new help text. The routine is called by VMI$CALLBACK PROVIDE_DCL_HELP filespec "filespec" is the name of the help file (.HLP assumed) to be used in the update. The routine returns the status returned by UPDATE_LIBRARY. Therefore, vmi$_success will be returned unless the help file is not found. 52 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications PROVIDE_FILE This routine is used to copy a file from the installation directory to an appropriate system directory. In addition, it is possible to override purging the destination directory, even if purging was requested. If the file is an installed image, it is possible to cause the new version to be reinstalled. The routine is called by VMI$CALLBACK PROVIDE_FILE result filespec location options "result" is a process logical name. On return, this symbol contains the file specification of the destination file. "filespec" is the name of the source file. The source file is assumed to be located in the installation directory. "location" is the device/directory specification which defines the system directory where the file is to be located. The destination file will have the same filename and filetype as the source file. Legal values of "options" are "K" and "R". o If "K" is specified, the file will not be purged in the destination directory, even if general purging was selected. o If "R" is specified, the file is assumed to be an installed image. The new version of the file will replace the current version (/REPLACE switch to INSTALL). Note that this will only be done if the effect of this routine is to create a new version of an existing file. If the file is new to the system, the re-installation is not done. The routine returns vmi$_success unless the source file does not exist or the actual file transfer (a MOVE_FILE operation) fails. 53 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications PROVIDE_IMAGE This routine is used to transfer an image file from the installation directory to the system area. The image may be either an executable or a sharable image. A small patch may optionally be made to the image before it is copied. First the routine verifies that the image file exists in the installation directory. Then, if the patch option was not specified, the procedure determines whether an old version of the image exists on the system. If the image is new, it is copied to the system using a MOVE_FILE command. If the image is a replacement of an existing image, then a slightly different flavor of MOVE_FILE command is used. In this latter case, the option to re-install the image is always taken. Therefore, PROVIDE_IMAGE should be used for images which are to be installed. If you specify (as an option) that the image is a sharable system image, then vmi$root:[syslib]imagelib.olb (the system sharable image library) will be updated with the new version of this image. The patch option allows minimal patches to be made to the image during the installation. This capability is limited, however, in that important syntax restrictions exist. While discussed below, it is recommended that the PATCH_IMAGE procedure (or the simple expedient of providing an image which does not require patching) be used instead. The calling sequence is VMI$CALLBACK PROVIDE_IMAGE result filespec location - options patch "result" is a process logical name. On output, it contains the fully qualified file specification for the image being moved to the system area. "filespec" is the file specification of the new image file. "location" is the device/directory where the image file should be stored. Valid "options" are "E", "I", "R", and "K". o The "E" parameter is used to specify that an on-the-fly patch (an ECO) is to be made to the image. If "E" is not specified, the "patch" parameter will be ignored. 54 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications o The "I" parameter is used to specify that the image should be replaced in the system image library VMI$ROOT:[SYSLIB]IMAGELIB.OLB. o The "R" parameter is used to cause the new image to replace the old image as an installed image in the system. This option is passed to MOVE_FILE. o The "K" parameter is used to override the current purge state of the installation for this particular image file. It is passed to MOVE_FILE. "patch" defines the patch which is to be applied to the image file before it is copied to the system area. In general, it may consist of a sequence of patch commands, separated by commas. Therefore, no patch command which includes a comma as part of its syntax may be used here. The contents of the "patch" string is broken into segments, using the comma to delimit each segment. Each segment begins with the argument to a SET ECO command. An UPDATE command follows each segment. Note that using the "patch" parameter in this way is made more difficult by the problem of how one builds a string parameter which contains internal carriage-returns. The problem here is that each "patch" segment begins with a fragment of a PATCH command and then should contain one or more additional commands, each of which would normally begin on a new line. The normal technique for building the appropriate value for the "patch" parameter is to specify it by "''F$FAO(...)'" in the calling sequence. By using the !/ F$FAO operator, a multi-line string can be built. The routine actually builds a temporary patch command file from the contents of the "patch" parameter. Each segment generates a fragment of the file which consists of a SET ECO command, followed by the patch commands of the fragment, followed by UPDATE. When all of the "patch" parameter segments have been used, the file is closed, used by PATCH, and the file is deleted. The routine returns vmi$_success unless a major error occurs. Major errors include such things as failure to find the source image file, failure of the MOVE_FILE command, and failure of the UPDATE_LIBRARY command which updates IMAGELIB.OLB. 55 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications RESTORE_SAVESET This routine is used to restore a secondary saveset from the distribution device. For both the primary saveset and all secondary savesets, the filename of the saveset is the product name. The primary saveset name has the filetype "A". Secondary savesets would have filetypes of "B", etc. Normally, an installation consists of a single saveset. However, the developer always has the option of using secondary savesets if he chooses. One case in which secondary savesets might be used is when the installer is given an option of whether some files are to be copied to his target system. The optional files could be placed in a secondary saveset for simplicity. Another case is a very large installation. By careful selection of what goes where, the peak disk utilization of a large installation could be reduced by using secondary savesets. The secondary savesets are always located on the same physical device as the primary saveset. The procedure is able to retry operations if failures occur during the saveset restoration. This includes handling multiple volumes of sequential disk devices. Note that it is never necessary to call this routine to restore the primary saveset -- VMSINSTAL does this for you. Also note that if secondary savesets are used, KITINSTAL.COM must be located on the primary saveset. The routine is called by VMI$CALLBACK RESTORE_SAVESET label option "label" is the file type of the saveset. Remember that the filename of the saveset is always the product name. For example, if installing version 2.3 of XYZ then the secondary saveset "B" would have saveset name "XYZ023.B". The only legal "option" is "N". If "option" is omitted, then the medium currently on the distribution device will be dismounted, and the new medium will be MOUNTed /FOREIGN. If "option" has the value "N", this will not occur. Therefore, if using a secondary saveset which is on the same physical medium as the primary saveset, you should specify "N" for "option". If you have specified "option" = "N" and the specified saveset is not found on the medium, then the action which occurs is medium-dependent. 56 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications - For a disk device which has vmi$remount set true (i.e. for the console device or for a sequential disk set mounted /FOREIGN), then the next volume of the set will be called for. - For a normally-mounted disk or for installation of the application over the network, the operation will fail. - For a magtape, the tape will be rewound so that the operation can be retried. This allows for the possibility that the specified saveset was positioned on the tape closer to BOT than the primary saveset. This rewind-retry operation will only be done once, however, before a failure is declared. The routine will return vmi$_success if the restoration of the saveset succeeds. If the saveset is not found or medium errors prevent a successful restoration, then vmi$_failure will be returned. SECURE_FILE This routine is used to change the attributes of a file, so that the file may be properly protected. The routine provides the ability to set the file ownership and file protection attributes of a specified file. The calling sequence is VMI$CALLBACK SECURE_FILE filespec owner protection "filespec" is the file specification of the file to be re-protected. The search order used insures that the file will be properly protected regardless of whether the installation is taking place in safety mode (in which case the file will still be in the installation directory) or in unsafe mode (in which case the file may have already been moved to the system area). "owner" is the new owner UIC. Brackets are required syntax. If the parameter is omitted, then the owner UIC is unchanged. "protection" is the new file protection for the file. This parameter is used as the argument to a SET PROTECTION command. The parentheses, which are used when more than one protection group is being specified, should NOT be included -- they are already in the command line in the routine. If omitted, the protection of the file is not changed. 57 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The routine returns vmi$_success unless the specified file cannot be found. SET The SET command will establish environmental conditions for the execution of VMSINSTAL. Using a SET command, you may indicate whether an Installation Verification Procedure (IVP) should be run, whether system files should be purged, whether the system must be rebooted, etc. SET IVP The SET IVP command is used to determine whether an Installation Verification Procedure (IVP) is executed as part of the installation procedure. The syntax is VMI$CALLBACK SET IVP option where "option" may take the value "ASK", "YES", or "NO". If the "ASK" option is chosen, the installer will be asked whether he wishes the IVP to be run. Most procedures use the ASK option. If no SET IVP command is issued, the default value will be SET IVP NO. The command always returns vmi$_success. SET PURGE The SET PURGE command is used to determine whether system files are purged when files are moved from the installation directory to the system area. The syntax is VMI$CALLBACK SET PURGE option where "option" may take the value "ASK", "YES", or "NO". If the "ASK" option is chosen, the installer will be asked whether he wishes files replaced by the installation to be purged. The default value is SET PURGE YES. Most installation procedures issue a SET PURGE ASK command. The command always returns vmi$_success. 58 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications SET REBOOT The SET REBOOT command is used to determine whether the system will be rebooted when the installation is complete. Rebooting, if selected, is automatic. That is, if the installation completes successfully and rebooting is chosen, then VMSINSTAL will invoke SYS$SYSTEM:SHUTDOWN.COM directly. The syntax is VMI$CALLBACK SET REBOOT option where "option" may take the value "YES" or "NO". The default value is SET REBOOT NO. This option should only be used when a reboot is required as part of the installation process. The routine always returns vmi$_success. SET SAFETY The SET SAFETY command is used to establish or change the safety mode with which VMSINSTAL is run. Setting of safety mode depends on the amount of disk space required for the installation and the amount of disk space available on the vmi$root volume. The syntax is VMI$CALLBACK SET SAFETY option peak_usage where "option" may take the value "YES", "NO", or "CONDITIONAL" and "peak_usage" is the number of blocks required for the installation. If "option" is "YES", then vmi$safety is set true (=1). The routine will return success unless the amount of free space on the vmi$root volume is less than 110% of the value specified in "peak_usage" (in units of blocks). If there is not enough space, the routine returns vmi$_failure. If "option" is "CONDITIONAL", then vmi$safety is set true (=1) if there is sufficient space for the installation (vmi$free_blocks > 110% of "peak_usage") and false (=0) otherwise. The routine always returns vmi$_success. If "option" is "NO", then vmi$safety is set false and the routine returns vmi$_success. The "peak_usage" parameter is not used. 59 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications Most installation procedures use SET SAFETY CONDITIONAL. SET STARTUP The SET STARTUP command is used to define a startup command file which is used as part of the initialization procedure for the application. The typical use of this command is for those applications in which a command procedure is placed in the site-specific startup file. The installation will move this file to the SYS$MANAGER area, but cannot edit your site-specific startup file. However, the initialization procedure needs to be executed if the IVP is expected to succeed. The solution to this situation is to use the SET STARTUP command to define this initialization file. When the IVP is executed, this file will be executed first, to set up the proper environment. The syntax is VMI$CALLBACK SET STARTUP filename where "filename" is the name of the initialization procedure. The command will define vmi$startup as a global symbol vmi$startup :== @vmi$root:[sysmgr]'filename' so that it can be executed when needed. The routine always returns vmi$_success. SUMSLP_TEXT The SUMSLP_TEXT command is used to update an ASCII file, using the SUMSLP editor. Therefore, its purpose is very similar to that of the PATCH_IMAGE command, except that PATCH_IMAGE operates on images, while SUMSLP_TEXT operates on text files. The SUMSLP_TEXT command also supports checksums on the text files, thus providing an enhancement to the normal operation of the SUMSLP editor. Checksum services are performed by a program called CHECKSUM. This program is built as a DCL command, although its command table is not part of the standard DCL. Therefore, a SET COMMAND is issued for the command file VMI$ROOT:[SYSEXE]CHKSUM.CLD. This defines CHECKSUM as a DCL command for the current process. The only capability which we need to consider for the CHECKSUM command is that if you issue the command 60 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications $ CHECKSUM file-spec then a local symbol "CHECKSUM$CHECKSUM" is created, which contains a 32-bit checksum of the file specified. Like PATCH_IMAGE, this routine uses a correction file. Also like PATCH_IMAGE, the calling parameters may either be specified in the command invocation or as a comment in the first line of the correction file. If the latter approach is used, the following format is required for the first line of the correction file: -;!target type startsum endsum where "-;!" must be the first three characters on the line and where the values of the four parameters must be separated by exactly one space each. SUMSLP_TEXT operates either on isolated text files or on modules in MACRO, TEXT, or HELP libraries. In the library case, the routine will extract the module from the library, update it, and put it back. The operation of the routine is as follows. First, if this is the first invocation of the routine, then the appropriate SET COMMAND is issued, to define the CHECKSUM command. Then, the routine determines whether the command parameters are defined in the calling sequence of the routine or in the first line of the correction file. If the latter, then the parameters are extracted from the correction file. Next, a dispatch is done, depending on whether the routine is correcting a file or a library module. If correcting a file, the checksum of the source file is calculated and compared with the known initial checksum. If correct, then the correction is applied (using EDIT/SUM). If the correction was applied to a system file, then the correction process moves a copy to the installation directory. In this case, a PROVIDE_FILE command is issued to move the corrected version back to the system area. If the correction was applied to a file in the installation directory, however, it is not necessary to move it back, because the routine assumes that someone else has taken that responsibility. If correcting a library module, then the "target" argument is parsed. In the file case, "target" contains the file name. However, in the library case, "target" contains both the library and module names. Then the module is extracted from the library and its checksum is computed and compared against the known initial checksum. If correct, them the correction is applied and UPDATE_LIBRARY is used to replace the corrected module. 61 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The calling sequence is VMI$CALLBACK SUMSLP_TEXT result slpfile target type - startsum endsum in the case in which the command is completely specified in the call, and VMI$CALLBACK SUMSLP_TEXT result target in the case in which "target", "type", "startsum", and "endsum" are specified in the first line of the correction file. "result" is a process logical name. On return, it is the name of the file or library updated by the routine. "slpfile" is the name of the source correction file. This file must be in the installation directory. "target" defines the target of the operation. If a file is to be updated, then it is the name of the file. If, on the other hand, a library module is to be updated, then "target" consists of the library file specification, followed by a comma, followed by the name of the module to be updated. "type" defines the type of update to be done. Legal values for "type" are "FILE", "MACRO", "TEXT", and "HELP". A value of "FILE" implies that a text file is to be updated. Values of "MACRO", "TEXT", or "HELP" imply that a module of a library of the specified type is to be updated. "startsum" is the checksum of the source (i.e. unmodified) file or module. Since the changes which SUMSLP makes are based on line numbers, it is essential that the proper version of the source module be used. Validating the source checksum with the value of "startsum" is a useful technique for making sure that the source module is as expected. The update will not be done if the checksums don't match. When building an installation procedure which uses the SUMSLP_TEXT routine, use CHECKSUM to calculate the value to use for "startsum". "endsum" is optional. Its value is the checksum of the updated version of the file or module. It is used when the checksum of the source module does not match the value specified in "startsum". In this case, "endsum" (if specified) is used to distinguish between the case in which the file or module has already been updated and the case in which the file or module has been changed in some other way. If the module has already been updated, then a success message is issued. Otherwise, an error message is issued to the effect that the file has been tampered with. If "endsum" is not specified, it is only possible to issue the latter message. 62 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The routine returns the status vmi$_success except when one of the following errors is found. * Correction file not found. * Source file not found. * In a file update, PROVIDE_FILE returned an error. * Source library not found. * In a library update, UPDATE_LIBRARY returned an error. * The source checksum does not match the "startsum" value and either "endsum" is not specified or the source checksum does not match the "endsum" value. This is the "TAMPER" error -- i.e. the file has been tampered with. TELL_QA The TELL_QA command is used to print a special message on the output terminal. If OPTIONS Q has been specified, then issuing the command VMI$CALLBACK TELL_QA message will cause the "message" to be printed on the terminal. It is not clear how DEC uses this. The obvious use is with respect to error reporting. However, VMSINSTAL does not seem to take advantage of this capability. The command, by the way, always return vmi$_success. UPDATE_ACCOUNT This routine is used to modify an existing account on the system. The routine defines both SYSUAF and NETUAF, so that it is possible to change both system and network proxy accounts using this facility. The routine is called by VMI$CALLBACK UPDATE_ACCOUNT userid switches "userid" is the account userid (i.e. the value entered in response to the LOGIN Username: prompt). "switches" is the set of AUTHORIZE switches used to define the account, such as /DEVICE, /DIRECTORY, etc. 63 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications The routine returns vmi$_success unless it cannot find the file VMI$ROOT:[SYSEXE]SYSUAF.DAT (the SYSAUF file). UPDATE_FILE This routine copies a file from the system area into the installation directory, preparing it for update. The operation is closely coupled with safety mode. Assume that the installation is proceeding in safety mode. Then the UPDATE_FILE command will look up the file. If the file is already in the installation directory (FIND_FILE returns status "W"), then the routine exits immediately. The assumption is that whoever moved that file into the installation directory will be responsible for moving it back. However, if the file is not currently in the installation directory, then UPDATE_FILE copies the file (BACKUP /OWNER=ORIGINAL) to the installation directory and issues a MOVE_FILE command to move it back. Recall that in safety mode, the MOVE_FILE does not actually move the file, but rather makes an entry in the defer-file for later execution. Therefore, the file is moved to the installation directory, where updates may be done, and set up to be moved back later. It will not be necessary to explicitly issue a command to move the file back to its original home. In unsafe mode, however, the file is only moved to the installation directory. The MOVE_FILE routine is not called in this case, since it would perform an immediate return of the file in unsafe mode. The calling sequence is VMI$CALLBACK UPDATE_FILE result filespec "result" is a process logical name. On return, this name contains the fully qualified file specification of the source file which is being moved. "filespec" is the fully-qualified input source-file specification. If the source file is not found, the routine returns vmi$_failure. If executed in unsafe mode or if the file is found in the installation directory (and hence if no call to MOVE_FILE is to be made), the routine returns vmi$_success. Otherwise, the routine returns the status from the MOVE_FILE command. 64 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications UPDATE_LIBRARY The UPDATE_LIBRARY command invokes the LIBRARY utility. This is done immediately, rather than in a deferred sense. Care is taken to record what is being done in case a crash occurs during the update. The routine looks up the library file in the system area to verify that it exists. It then invokes the librarian to perform the requested update. The structure of the command is such that it is possible to invoke either the VMS LIBRARIAN or the RSX LBR utility. The calling sequence is VMI$CALLBACK UPDATE_LIBRARY result libfile type switches - filespec "result" is a process logical name. On output, it contains the fully qualified file specification of the library file. "libfile" is the input library file specification. The library file must be a system file, not a file in the installation directory. "type" is a library switch MINUS THE INITIAL "/". This parameter may be used in two ways. If the RSX librarian is to be invoked, the "type" parameter should be "RSX". If the VMS librarian is to be invoked, then the appropriate switch which defines the library type (HELP, TEXT, etc.) should be used here. Note that since the library command being issued already contains the "/", this parameter should NEVER be omitted. "switches" contains whatever additional switches are needed on the library command. In a typical example, "switches" = "/REPLACE". "filespec" contains the source file specification for the file which will be used to update the library. The routine always returns vmi$_success unless the library file is not found. 65 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications Example of a User-Written VMSINSTAL Procedure In this chapter, we will develop a release procedure for a simple software product. While the example is simple, it contains the essential features of every installation. Components of the Example Product For our example, we will install version V1.0 of a program called SPLAT. This program will be assumed to be implemented as a DCL command. System help will be available for SPLAT, as will a User's Guide. The procedure STRTSPLAT.COM must be executed at system startup for SPLAT to work correctly. In addition, the file SPLAT.DAT is required by the program and needs to be located in [SYSEXE]. No sources are provided in our example, nor is it necessary to re-link the software for the target system. An installation verification procedure exists for SPLAT. It is the file SPLATIVP.COM. Planning the Release Kit The following files must be included in the release kit for SPLAT. The length of each file is shown in parentheses. o KITINSTAL.COM -- (3) -- the installation command procedure. o SPLAT.EXE -- (23) -- the image file. o SPLAT.CLD -- (2) -- the DCL Command definition file. o SPLAT.HLP -- (10) -- the HELP module o SPLAT.DOC -- (57) -- the User's Guide o STRTSPLAT.COM -- (2) -- the startup command procedure o SPLAT.DAT -- (140) -- the required data file. o SPLATIVP.COM -- (5) -- the Installation Verification Procedure 66 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications This release is version V1.0, so the release kit will be SPLAT010. The release kit will require 242 blocks of disk space. When the installation is complete, all of the above files except the CLD file, KITINSTAL, and SPLATIVP will reside on the system. Therefore the net disk utilization is 232 blocks. The peak utilization will be the sum of the these two numbers (474 blocks) plus 310 blocks for the extra copies of DCLTABLES which are created in safety mode plus a bit for things like the marker file and the defer file. We will choose conservative figures of 250 blocks net and 800 blocks peak disk utilization. We assume that SPLAT requires VMS version V3.0 or later to run correctly. Building KITINSTAL.COM The next step is to build KITINSTAL.COM. The following command file installs SPLAT. The numbers in parentheses refer to comments which follow the example command file. (1) $ on control_y then goto CONTROL_Y_EXIT $ on error then exit $status (2) $ if p1 .eqs. "VMI$_INSTALL" then goto INSTALL $ if p1 .eqs. "VMI$_IVP" then goto IVP $ exit vmi$_unsupported (3) $CONTROL_Y_EXIT: $ vmi$callback CONTROL_Y $ exit vmi$_failure (4) $INSTALL: (5) $ vmi$callback CHECK_VMS_VERSION kit$ 030 $ if .not. kit$ then exit vmi$_failure (6) $ vmi$callback CHECK_NET_UTILIZATION kit$ 250 $ if .not. kit$ then exit vmi$_failure (7) $ vmi$callback SET safety conditional 800 (8) $ vmi$callback SET purge ask (9) $ vmi$callback SET IVP ask (10) $ vmi$callback PROVIDE_IMAGE kit$ splat.exe - vmi$root:[sysexe] (11) $ vmi$callback PROVIDE_DCL_COMMAND splat.cld 67 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications (12) $ vmi$callback PROVIDE_DCL_HELP splat.hlp (13) $ vmi$callback PROVIDE_FILE kit$ splat.doc - vmi$root:[sysupd] (14) $ vmi$callback PROVIDE_FILE kit$ strtsplat.com - vmi$root:[sysmgr] $ vmi$callback SET STARTUP strtsplat.com (15) $ vmi$callback PROVIDE_FILE kit$ splat.dat - vmi$root:[sysexe] (16) $ exit vmi$_success (17) $IVP: (18) $ @vmi$kwd:splativp.com (19) $ exit $status The following commentary describes each of the code segments above. (1) Set up error handling. If a CNTL/Y is typed, execute the code at CONTROL_Y_EXIT. If there is an error, return with the error status. (2) Dispatch to the appropriate portion of KITINSTAL. The KITINSTAL procedure is invoked twice -- once for installation (with P1 = VMI$_INSTALL) and once to execute the IVP (with P1 = VMI$_IVP). If KITINSTAL gets called any other way, it is an error. (3) Process a CNTL/Y by issuing a message (call to CONTROL_Y) and exiting with failure. (4) Begin the installation portion of the procedure. (5) Make sure that the version of VMS is at least V3.0. (6) Make sure that there are 250 blocks available on the disk for the installation. (7) Since Safety Mode requires 800 blocks in this example, turn on safety mode only if that much disk space is available. (8) Ask the user if old copies of files created by KITINSTAL should be purged. (9) Ask the user if he wishes the IVP to be run. 68 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications (10) Copy the SPLAT.EXE file to [SYSEXE]. (11) Update DCLTABLES.EXE to include the SPLAT command. (12) Update the system help file to include help for SPLAT. (13) Copy the User's Guide to [SYSUPD]. (14) Copy the startup command file to [SYSMGR] and set things up so that it will be invoked before executing the IVP. (15) Copy the required data file to [SYSEXE]. (16) Done with the installation. Exit with a success status code. (17) Begin the Installation Verification Procedure portion of KITINSTAL. (18) Execute the IVP. (19) Return with the status returned by the IVP command file. This way, the caller (VMSINSTAL) will know whether the IVP succeeded or failed. Build the Release Kit Having created KITINSTAL, the last step is to build the release kit. We will assume that you choose to distribute the kit on a 9-track magtape. On your system, your tape drive is MFA0. To build the release kit, issue the following commands. $ allocate mfa0: tape $ initialize tape: splat $ mount/foreign tape $ backup/interchange/verify - $_ /comment="Release Kit for SPLAT" - $_ kitinstal.com,splat.exe,splat.cld,splat.hlp,- $_ splat.doc,strtsplat.com,splat.dat,splativp.com - $_ tape:splat010.a/save $ dismount tape: $ deallocate tape: $ deassign tape: The release kit is now complete. To install SPLAT, log in to the SYSTEM account and type 69 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications $ set uic [1,4] $ set default sys$update $ @vmsinstal splat mfa0: options C,L,S assuming that you want all possible information about the installation. VMSINSTAL will correctly install this product. VMSINSTAL Futures At the fall '84 DECUS symposium, a pre-field test version of VMS V4.0 was on display in the exhibit hall. The V4.0 version of VMSINSTAL was included. The following remarks describe the most significant changes to the procedure, based on an examination of that file. Of course, we have no way of knowing at this time what the shipped version of VMSINSTAL will look like. Get Option A new option is available in the VMSINSTAL command line. By specifying OPTIONS G, you can copy a release kit from the distribution medium to a disk directory for later installation. This option will only copy the VMSINSTAL savesets; it does not actually install the software. Therefore, this operation can be performed on a live system and does not require you to operate standalone. MOVE_FILE The MOVE_FILE callback routine will accept the I option. If specified, this option will cause the file being moved to be replaced in IMAGELIB.OLB. 70 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications ASK The ASK callback routine has been enhanced with new options. - Option S is now required if a string to specify a string data type. - Option N has been added. This option allows a null argument to be specified. - Option Z has been added. Using this option, if the user enters a CNTL/Z as the response to a question, the string "^Z" is returned to the caller. GET_SYSTEM_PARAMETER This callback routine now uses the F$GETSYI lexical function instead of SYSGEN. I wonder if F$GETSYI is being enhanced? MESSAGE The MESSAGE callback routine is capable of generating a two-line message. The first line begins with "%", while the second begins with "-". PRODUCT The PRODUCT callback routine is new. It provides for product-specific callback routines. This feature should be extremely useful for complex product installations. 71 PAGESWAPPER - April 1984 - Volume 5 Number 10 Using VMSINSTAL with User-Written Applications RENAME_FILE This is a new callback routine. It renames a system file. 72 PAGESWAPPER - April 1984 - Volume 5 Number 10 VAX Sessions at the Spring 1984 Symposium VAX Sessions at the Spring 1984 Symposium Jeffrey S. Jalbert VAX Systems SIG Symposium Coordinator Jack D. Cundiff VAX Systems SIG Assistant Symposium Coordinator The following are the VAX sessions by day: * * * MONDAY JUNE 4, 1984 * * * W002 9:00 AM VAX SYSTEMS SIG ROADMAP W098 10:00 AM VAX SYSTEM UPDATE W122 11:00 AM VMS SYSTEM UPDATE W138 12:00 PM LANGUAGES AND TOOLS OVERVIEW W101 1:00 PM VAX ENHANCEMENTS W063 2:00 PM THE BOURNE SHELL ON VMS W130 2:30 PM MICROVAX TECHNICAL UPDATE W129 3:30 PM VAXELN TECHNICAL OVERVIEW W078 3:30 PM VAX LISP W084 3:30 PM VAX SYSTEMS SIG WORKING GROUP CHAIRMAN'S MEETING W089 4:30 PM ARTIFICAIL INTELLIGENCE WORKING GROUP W066 5:00 PM NEW VAX PRODUCTS OVERVIEW AND CPU UPGRADE PROGRAM L038 5:30 PM VAX DEBUG VERSON 4.0 W035 5:30 PM ORGANIZATION MEETING OF THE VAXELAN WORKING GROUP W038 6:00 PM IMAGE ACTIVATION AND INTIALIZATION ON VAX/VMS L037 6:30 PM VAX DEBUG TUTORIAL W022 6:30 PM VAX/ELAN -- FIELD TEST REPORT AND CASE STUDY W097 7:30 PM DEVICE INTERACTIONS WITH VAX/VMS W146 7:30 PM VAX SYSTEMS SIG LUG REPRESENTATIVES MEETING W004 8:30 PM DIGITAL ASKS THE VAX USERS W017 9:30 PM VAX NOVICE QUESTIONS AND ANSWERS * * * TUESDAY JUNE 5, 1984 * * * W125 9:00 AM VAXCLUSTER TECHNICAL CONCEPTS W079 9:00 AM PROGRAMMING IN VAX LISP W007 9:00 AM VAX SYSTEMS SIG PROJECT ACCOUNTING WORKING GROUP W081 10:00 AM GETTING STARTED WITH ARTIFICAL INTELLIGENCE W085 10:00 AM VAX SYSTEM SIG SYSTEM MANAGEMENT WORKING GROUP MEETING W115 11:00 AM SUPPORTING NEW PROCESSORS UNDER VMS W077 11:00 AM JSC LIFE SCIENCE DATA SYSTEM-SPACELAB FLIGHT EXPERIMENT W074 11:00 AM VMS NETWORK WORKING GROUP MEETING W105 11:30 AM SPACELAB-1 LIFE SCIENCE DATA SYSTEM DESIGN (JSC) W111 12:00 PM VAX/VMS UTILITIES - ENHANCEMENTS IN V4.0 W113 12:00 PM MICROVAX ARCHITECTURE SUPPORT IN MICROVMS W006 12:00 PM VAX SYSTEMS SIG COMMERCIAL WORKING GROUP MEETING W062 1:00 PM DESIGN CONSIDERATION-IMPLEMENTATING BOURNE SHELL ON VMS W121 1:00 PM VMS PROCESSORS SUPPORT 73 PAGESWAPPER - April 1984 - Volume 5 Number 10 VAX Sessions at the Spring 1984 Symposium W072 1:00 PM VAX REAL-TIME WORKING GROUP MEETING W120 2:00 PM VMS V4 BATCH AND PRINT W117 3:00 PM VAX-11 RMS ENHANCEMENTS FOR VMS V4.0 W096 3:00 PM FOREIGN DEVICES WORKING GROUP U026 3:00 PM VAX DOCUMENTATION W119 4:00 PM USER WRITTEN PRINT SYMBIONTS W034 4:00 PM VAX/VMS ACNET: A HIGH PERFORMANCE DATA AQUISTION AND CONTROL NETWORK IMPLEMENTATION W018 4:00 PM VAX NOVICE SOFTWARE CLINIC W049 5:00 PM VAX-11 SORT/MERGE VERSION 4.0 W041 5:00 PM HOW I MANAGE MY VAX SYSTEM (PANEL) W118 6:00 PM VMS EXECUTIVE ENHANCEMENTS TO THE NEXT MAJOR RELEASE * * * WEDNESDAY JUNE 6, 1984 * * * W139 9:00 AM CONNECTING TERMINALS TO VAX VIA TERMINAL SERVERS W036 9:00 AM NOVICE REAL-TIME PROCESSING USING VAX/VMS W107 10:00 AM VMS TERMINAL DRIVER U011 10:00 AM SYSTEM MANAGEMENT FOR THE NEW MANAGER W100 11:00 AM VAX SYSTEM INTEGRITY MONITOR W028 11:00 AM VAX/VMS DCL FOR THE NEW USER W029 11:30 AM INTRODUCTION TO VMS COMMAND PROCEDURES W142 12:00 PM VAX DIAGNOSTIC ARCHITECTURE W143 12:30 PM NOVICE VAX CONFIGUATIONS W116 1:00 PM FILE NAMES, LOGICAL NAMES AND SEARCH LISTS IN VMS V4 W065 2:00 PM WHAT'S NEW IN THE RUN-TIME-LIBRARY FOR VMS V4 W034 2:00 PM NOVICE REAL-TIME PROCESSING USING VAXELAN W086 2:00 PM NOVICE SYSTEM MANAGERS CLINIC W064 3:00 PM SCREEN MANAGEMENT IN THE VAX RUN-TIME LIBRARY W005 3:00 PM VAX/VMS NOVICE RMS AND DISK TUNING W109 4:00 PM DCL AND THE COMMAND DEFINITION UTILITY W014 4:00 PM SECURITY TIPS FOR THE NEW VMS SYSTEMS MANAGER W012 4:00 PM ADVANCED VAX/VMS SOFTWARE CLINIC W095 5:00 PM EFFECTIVE USAGE OF THE VAX-11 SYMBOLIC DEBUGGER W108 5:30 PM A USER'S GUIDE TO AUTOGEN W102 6:00 PM VAX INTERCONNECTS W013 6:00 PM UNDERSTANDING VMS IMAGE ACCOUNTING FILES W112 6:00 PM MICROVMSOVMS SUPPORT FOR MICROVAX I * * * THURSDAY JUNE 7, 1984 * * * W132 9:00 AM VMS V4 PERFORMANCE W131 10:00 AM VMS PERFORMANCE IN A VAXCLUSTER W023 10:00 AM VAX MIGRATION / HOST-DEVELOPMENT WORKSHOP W019 11:00 AM VAX SYSTEMS SIG SYSTEM IMPROVEMENT REQUESTS W141 12:30 PM DISK SYSTEM PERFORMANCE IN VAX/VMS W114 12:30 PM WRITING PRIVILEGED SOFTWARE FOR MICROVAX SYSTEM W126 1:30 PM SECURITY MECHANISMS FOR VAX/VMS 74 PAGESWAPPER - April 1984 - Volume 5 Number 10 VAX Sessions at the Spring 1984 Symposium W135 1:30 PM DESIGNING HIGH PERFORMANCE REALTIME APPLICATIONS FOR VAX/VMS W045 2:30 PM PROTECTING YOUR VMS SYSTEM (AGAINST HACKERS) W024 2:30 PM VAX TAPECOPY USERS'S FORUM W091 3:30 PM CONTROLLER BASED SHADOWING W133 4:30 PM DESIGNING & IMPLEMENTING VAX/VMS APPLICATIONS FOR PERFORMANCE W042 4:30 PM VAX SITE PREPARATION W103 4:30 PM VAX HIGH-END TECHNOLOGY W136 5:30 PM DISK PERFORMANCE IN A VAX CLUSTER W016 5:30 PM VMS SYSGEN PARAMETERS W128 6:30 PM VAXELN UPDATE / QUESTIONS AND ANSWERS I039 6:30 PM 780 MEMORY PERFORMANCE W015 6:30 PM VMS BACKUPS - ARE YOU SURE YOU HAVE A GOOD COPY OF YOUR DATA? W094 7:30 PM A SYSTEM FOR AIRCRAFT TEST DATA ANALYSIS WITH PROVISIONS FOR REMOTE OPERATIONS W021 7:30 PM VAX USER-WRITTEN SYSTEM SERVICES W008 8:00 PM VAX MAGIC, WAR STORIES, AND HORROR TALES * * * FRIDAY JUNE 8, 1984 * * * W134 9:00 AM VAX/VMS SYSTEM PERFORMANCE MANAGEMENT W140 9:00 AM XSEL AND EXPERT SYSTEM FOR THE DEC SALES FORCE W110 10:00 AM VAX/VMS PACKAGING AND DISTRIBUTION W090 10:00 AM USING AN EXPERT SYSTEM TO TUNE VMS W083 11:00 AM MIGRATION TO VAXCLUSTERS W080 11:00 AM WORKING WITH VAX OPS5 W051 11:30 AM CONFIGURATION MANAGEMENT ON VMS W009 12:00 PM FT COPY-FOREIGN TAPE COPY FOR VMS W127 12:30 PM PANEL DISCUSSION ON VAX/VMS SECURITY MECHANISMS W076 12:30 PM VAX STATION SYSTEM MANAGEMENT W099 1:30 PM VAX HARDWARE PANEL W047 1:30 PM VAX SECURITY WORKING GROUP MEETING W003 2:30 PM VAX SIG BUSINESS MEETING W010 3:00 PM VAX SYSTEMS ADVANCED QUESTIONS AND ANSWER 75 PAGESWAPPER - April 1984 - Volume 5 Number 10 Eagles and Egg on Your Face Eagles and Egg on Your Face by Paula Sharick reprinted from the March 1984 LUG*NOTES of the Rocky Mountain VAX Local Users Group Here is a little story that I hope will save all you Eagle users some time and energy and phone calls. Being way high on the VMS distribution list for upgrades, we received our copy of 3.5 in early January. Last week, we dutifully scheduled an extra two and 1/2 hours to combine the upgrade with our normal Friday backup procedures and patiently sat while all 5 floppies were processed. then, ready to backup the new system disk, we booted 3.5 only to find the dubious indent 10;**** FATAL BUG CHECK 10;CURRENT PROCESS: NULL printed on the console. After RDC tried the same thing twice again, our DEC debugger asked innocently: Do you have any SI drives on your VAX? It seems, upon reference to the back pages of the release notes, that 3.5 replaces the DRDRIVER.EXE image completely, and of course causes 3.5 to crash since the new driver wipes out all of SI's patches. Several phone calls later, the following story emerged. I might point out that none of this information was relayed to us either before, during, or after we bought the drives. Since we started with VMS 3.3, I'll use it for our example. 1. Before you (or an SI engineer) patch DRDRIVER/device tables you MUST make a copy of the vanilla DEC DRDRIVER. My technical contact recommended the copy be named DRDRIVEr.V33 so it is identified by version number. 2. Then either you or your SI rep run SI's patch procedure, called SYS$UPDATE:SI303.COM named for the highest version of VMS supported by the patches. although the SI tech mentioned that it would be called automatically on upgrades, I could find no reference to the COM file in any VMS file, or in our startup procedures. 3. When a VMS upgrade shows up, rename DRDRIVER.V33 to DRDRIVER.EXE before you do the upgrade so you end up with another clean DEC driver when you are done. Then make a copy of the new DRDRIVER called DRDRIVER.V34. 76 PAGESWAPPER - April 1984 - Volume 5 Number 10 Eagles and Egg on Your Face The current SI patches should be called at the end of the upgrade procedure, so only the clean DEC driver is patched. 4. SI has at least one newer version of their COM file, called SI304.COM, which you have to request. When I went to check on the version we have, the internal documentation says that it is good for versions 3.0, 3.1 and 3.2. Now why is it called SI303.COM when VMS3.3 is not included? And why don't we have SI304.COM?? 5. Patches for 3.5 will not be available from SI until mid-March. Now that all you SI fans have the story, I have two comments to make. First, SI should take responsibility for notifying its customers when an upgrade will fail so we don't have to waste several hours of machine time coming to the same conclusion. Second, SI should improve their automatic distribution for patches so customers receive them as soon as they are available. According to my technical contact, SI currently has no method for informing its users in either of these areas. 77 PAGESWAPPER - April 1984 - Volume 5 Number 10 INPUT/OUTPUT INPUT/OUTPUT A SIG Information Interchange A form for INPUT/OUTPUT submissions is available at the back of the issue. INPUT/OUTPUT 273 Caption: LISP & LISP Compiler - Reply to I/O # 207 Message: A Le_Lisp environment including an interpreter, a compiler and a full-screen text editor is available on VAX11/780 VMS. Unfortunately, we sell it! (Unless you are a research center or laboratory...) Contact: Patrick Clement CRIL 12 bis, rue Jean Jaures 92807 PUTEAUX - FRANCE (1) 776-34-37 Date: February 8, 1984 INPUT/OUTPUT 274 Caption: VAX/VMS 11/730 Device Driver Message: We are looking for VAX/VMS 11/730 device driver for a Grinnell 274 image processing display system. We talk to the Grinnell 274 through DR11W mode B. Contact: Eric Nicole Laboratoire D'Informatique Medicale C.H.R.U. Le Bocage B.P. 1542 21034 Dijon Cedex France Date: February 21, 1984 78 PAGESWAPPER - April 1984 - Volume 5 Number 10 INPUT/OUTPUT INPUT/OUTPUT 275 Caption: Cursor Below EDT's [EOB] - Reply to I/O # 215 Message: The easiest solution for this problem is to hit - Screen Refresh, - Screen Refresh or (SEL) of the keypad - Reset. If none of these suggestions work press before the above keystroke(s). The problem belongs to EDT not your terminal(s). If you still have to press , then you should have submitted an SPR if you haven't already done so. Contact: William Mason Computing Centre, University of Newcastle N.S.W., Australia 2308 (044) 68-5563 Date: February 20, 1984 INPUT/OUTPUT 276 Caption: Need Intel format Linkage Editor for 8085 Message: We are in need of a Linkage Editor, to run under VAX/VMS, that will link Intel format 8085 object files. The object files are created by the PL/M compiler running under MDS. Identifiers of up to 31 characters must be processed. An accompanying librarian would be useful. Contact: Don Becker Edwards 625 Sixth Street East Owen Sound, Ontario, Canada N4K 1G5 (519) 376-2430 Date: February 21, 1984 INPUT/OUTPUT 277 Caption: CENSPAC (Version 3) converted to VMS Message: We are converting the Census Bureau's CENSPAC (Version 3) software package to VMS and would like to talk to anyone who has already done it. We might even be interested in acquiring your conversion. 79 PAGESWAPPER - April 1984 - Volume 5 Number 10 INPUT/OUTPUT Contact: Bob Hogan County of Orange/C.A.O. 10 Civic Center Plaza Santa Ana, CA 92701 (714) 834-5599 Date: March 2, 1984 INPUT/OUTPUT 278 Caption: TU-58 on VAX11/780 Message: We would like to install a TU-58 on our system to provide our customers who have 11/750's with a more portable software distribution medium. Does anybody out there have any information on how to do this? Contact: Marc Reid Boston Systems Office 469 Moody Street Waltham, MA 02154 (617) 894-7800 x345 Date: February 27, 1984 INPUT/OUTPUT 279 Caption: LOGO Package Required for VAX Message: We are upgrading our PDP11/40 to a second VAX 11/750 and are urgently seeking a LOGO interpreter for VMS. LOGO is used for most introductory programming courses. Any help locating an interpreter or source code would be greatly appreciated. Contact: John G. Crowe School of Mines and Industries P.O. Box 668 Baccarat Victoria Australia 3350 053 315911 Date: February 27, 1984 80 PAGESWAPPER - April 1984 - Volume 5 Number 10 INPUT/OUTPUT INPUT/OUTPUT 280 Caption: REDUCE Computeralgebra Message: Looking for software which can do symbolic mathematical computations under VMS. REDUCE is written in a dialect of LISP called Standard LISP. Does anyone know about such an implementation for VAX/VMS? Contact: Ingemar Sjors " Computing Centre, FFA Box 11 021 161 11 Bromma, Sweden Telex 107 25 08-802100 Date: February 28, 1984 INPUT/OUTPUT 281 Caption: VMS to 68000 C Cross Compiler Message: I am looking for a C compiler which runs under VMS and produces code for a 68000 based machine. Contact: Linda Hunt NASA Langley Research Center, MS 130 Hampton, VA 23665 (804) 865-3681 Date: February 29, 1984 INPUT/OUTPUT 282 Caption: File Archiving Program - Reply to I/O #186 Message: COSMIC, NASA's Computer Software Management and Infomation Center, has a file archiving program called ARCH (COSMIC Program NPO-16274). It keeps an on-line catalog of archived files. It is not clear from the summary if the software will issue a mount command to the operator. (This answer supplied by Linda A. Hunt, address as in previous I/O). Contact: COSMIC 112 Barrow Hall The University of Georgia Athens, GA 30602 (404) 542-3265 81 PAGESWAPPER - April 1984 - Volume 5 Number 10 INPUT/OUTPUT Date: February 29, 1984 82 PAGESWAPPER - April 1984 - Volume 5 Number 10 LUG Agenda LUG Agenda The following LUG meeting information is published with the understanding that Pageswapper readers will receive it too late to attend the meetings. The purpose, rather, is to share meeting topic ideas among LUGS. o BAYVAX LUG (San Francisco area) - Thursday April 5, 1984 David Herman, who is the project manager of the DIGITAL SOFTWARE INFORMATION NETWORK (otherwise known as the Problem Data base), will make a presentation on this new service offered to telephone support customers. He will also give a brief overview of all the software support services offered by the Colorado Springs operation. Dave has been leading the Problem Data base effort for the last year and brings with him 4 years of experience with the Software Support Services Operation. Michael Preston, who is a System Design consultant with Pacific Bell, will speak on the services and products that Pacific Bell now offers. Subjects scheduled to be discussed include the new corporate structure, who to call for help, and what services are available. A discussion of products such as DDS; high capacity transport service, local area networks, fiber optics and digital termination systems will complete the presentation to be followed by a question and answer period. Mr. Preston currently handles priority accounts for the Marketing Department of Pacific Bell. During his 4 year career with the company, he has designed networks and implemented systems for Rockwell, General Motors, and General Electric to name a few. He is currently assigned statewide responsibility for the data needs of the Lockheed account. 83 PAGESWAPPER - April 1984 - Volume 5 Number 10 VAX System SIG Committee List VAX System SIG Committee List As of November 2, 1983 Joe Angelico - Volunteer Coordinator and System Management US Coast Guard CCGD8(DT) Hale Boggs Federal Building 500 Camp Street, New Orleans, LA. 70130 June Baker - Planning Joe L. Bingham - Librarian Mantech International 2320 Mill Road Alexandria, VA 22314 C. Doug Brown - Security Sandia Labs P.O. Box 2644 Albuquerque, NM 87185 Jack Cundiff - Assistant Symposium Coordinator Muskigum College New Concord, OH 43762 James R. Cutler - Hardware Software Results Corporation 2887 Silver Drive Columbus, OH 43211 Doug Dickey - Data Management SIG Interface CTEC, Inc. 6862 Elm Street McLean, VA 22101 Jim Downward - Migration and Host Development KMG Fusion Inc. 3621 So State Road, P.O. Box 1567 Ann Arbor MI 48106 Dan Fleury - Education University of Hartford West Hartford, CT 06117 Dennis Frayne - Real Time/Process Control McDonnell Douglas 5301 Bolsa Avenue Huntington Beach, CA 92646 Carl E. Friedberg - Internals In House Systems 165 William Street 84 PAGESWAPPER - April 1984 - Volume 5 Number 10 VAX System SIG Committee List New York, NY 10038 Stephen Gill - Commercial Ball Aerospace P.O. Box 1062 Boulder, Colorado 80306 Don Golden - Overseas Coordinator 500 Corporate Drive Sugarland, TX 77478 Gary Grebus - System Improvement Request Battelle Columbis Labs 505 King Avenue Columbus, OH 43201 Dr. Mark Hale - Education University of Florida 411 Weil Hall Gainesville, FL 32611 B. Hancock - Network Sohio Petroleum Company Two Lincoln Center 5420 LBJ Freeway, Suite 900/LB 03 Dallas, TX 75240 R. Haydt - Foreign Devices, Hardware/Software Information Consultants International Incorporated P. O. Box 2014, E. V. STA Ormond Beach, FL 32074 Jeffrey S. Jalbert - Symposium Coordinator Dennison University Granville, OH 43023 Ken Johnson - Handouts 800 N. Lindbergh Monsanto MS V2B St. Louis, MO 63043 Lawrence J. Kilgallen - Newsletter Editor Box 81, MIT Station Cambridge, MA 02139-0901 Margaret Knox - Chair Computation Center University of Texas Austin, Texas 78712 Ross W. Miller - Vice Chair and Working Group Coordinator Online Data Processing, Inc. N 637 Hamilton Spokane, WA 99202 85 PAGESWAPPER - April 1984 - Volume 5 Number 10 VAX System SIG Committee List Bob Robbins - VAXElan Array Computer Consultants 5364 Woodvale Drive Sarasota, FL 33582 Larry Robertson - Real Time/Process Control Bear Computer Systems Inc. 5651 Case Avenue North Hollywood, CA P. Sandwell - Graphics Seismograph Service Corporation P. O. Box 1590 Tulsa, OK 74102 David Schmidt - LUG Coordinator Management Sciences Associates 5100 Centre Avenue Pittsburgh, PA 15232 Al Siegel - Advisor Battelle Memorial Institute 505 King Avenue Columbus, OH 43201 D. Slater - Artificial Intelligence Mantech International 2320 Mill Road Alexandria, VA 22314 Louise Wholey - Languages and Tools Measurex Corporation One Results Way Cupertino, CA 95014 Douglas J. Wilson - Office Automation MIT Joint Computer Facility Room 5-137, 22 Massachusetts Avenue Cambridge, MA 02139 86 PAGESWAPPER - April 1984 - Volume 5 Number 10 INPUT/OUTPUT Submission Form INPUT/OUTPUT Submission Form A SIG Information Interchange Please reprint in the next issue of the Pageswapper If this is a reply to a previous I/O, which number? ________ Caption: ______________________________________________________ Message: ______________________________________________________ ________________________________________________________________ ________________________________________________________________ ________________________________________________________________ ________________________________________________________________ ________________________________________________________________ ________________________________________________________________ Contact: Name _______________________________________________________ Address ____________________________________________________ ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ Telephone ____________________________ Signature _____________________________ Date ________________ Mail this form to: PAGESWAPPER Editor, DECUS, MRO2-1/C11, One Iron Way, Marlborough, MA 01752, USA 87 PAGESWAPPER - April 1984 - Volume 5 Number 10 INPUT/OUTPUT Submission Form Tear out to submit an I/O item PAGESWAPPER Editor DECUS, MRO2-1/C11 One Iron Way Marlborough, MA 01752 USA 88 PAGESWAPPER - April 1984 - Volume 5 Number 10 System Improvement Request Submission Form System Improvement Request Submission Form Page 1 of _____ ________________________________________________________________ Submittor: Firm: Address: Phone: ________________________________________________________________ How to write an SIR: Describe the capability you would like to see available on VAX systems. Be as specific as possible. Please don't assume we know how it's done on the XYZ system. Justify why the capability would be useful and give an example of its use. If you wish, suggest a possible implementation of your request. ________________________________________________________________ Abstract (Please limit to four lines): ________________________________________________________________ Description and examples (use additional pages if required) 89 PAGESWAPPER - April 1984 - Volume 5 Number 10 System Improvement Request Submission Form Tear out to submit an SIR Gary L. Grebus Battelle Columbus Laboratories 505 King Avenue Columbus, Ohio 43201 USA 90