.NONUMBER .LM 0 ^PY^- .PAGE SIZE 58,85 .LM 10 .RM 75 .NO FILL .NO JUSTIFY # .SKIP 5 .CENTER The RSX Multi-Tasker .CENTER March, 1987 .SKIP .CENTER ^IS144^G"Uchronia"^IS204^G .SKIP .CENTER Fine Realtime Commentary Since 1975 .SKIP 6 .CENTER ^&Table of Contents\& .SKIP 2 .TAB STOPS 60 Food for Thought RSX-1 The Editor's Corner RSX-1 Craftsmanship RSX-2 Submitting Articles to the Multi-Tasker RSX-5 And That's The Way Things Are RSX-6 DECnet FALLOG SPR RSX-6 INS and BOO SPR RSX-8 Modifying RSX CLI Prompts RSX-9 The Notebooks of Justin L. Hewser RSX-12 .JUSTIFY .FILL .PAGE .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT Food for Thought .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT # .SKIP 7 .AUTOPARAGRAPH .CENTER ^&Food for Thought\& .SKIP "In this galaxy, there's a mathematical probability of three million Earth-type planets. And in all of the universe, three million, million galaxies like this. But in all of that, and perhaps more, only one of each of us." .SKIP 2 .INDENT 30 ^IS144^G- Dr. Leonard McCoy^IS204^G .INDENT 30 ^IS144^G##Star Trek, "Balance of Terror"^IS204^G .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT The Editor's Corner .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .SKIP 9 .CENTER ^&The Editor's Corner\& .SKIP .CENTER Bruce R. Mitchell .SKIP Well, lazengemmum, here's fair warning before we jump off into this month's issue. This editorial is longer than usual - the editor's crank was recently turned relative to one of his pet peeves. However, like icky medicine, if you swallow it all I promise a worthwhile and educational experience. It's good for what ails 'ya. As we go to press, in late January, the DECUS Board should be inundated with responses from their user survey concerning the new DEC software licensing policy. Myself, I was unhappy that the survey cards didn't have multiple choice boxes. I would have suggested boxes labeled "Egregious", "We're DEC and You're Not", and "Robber Baron Tactics" for starters. There are interesting rumors floating about the SIG. One concerns a senior SIG wizard who is reputed to have implemented ODS-2 under RSX-11M-Plus. That's the VAX/VMS file system, for all us RSX diehards. This is reported to have been accomplished by stealth, deceit, trickery, chicanery, double-dealing - wups, wrong project. It is reported to have been done through divine intervention, the consumption of two cases of brew, and a bet with Brian McCarthy. The stakes of the bet remain unknown at this time. It is also rumored that M-Plus Version 4.0 is in field test. Changes in the operating system, and new features thereof, remain a mystery. Nobody's talking. There are dark whisperings of new caching algorithms and new device support, though. As news trickles in, we'll keep you up to date. On to the contents. In this issue, we have SPRs again. My goodness, do they never end? (I guess not, judging from comments the Editor has heard about Update C of M-Plus.)# We have an article on how to change CLI prompts by subtle trickery and sleight-of-hand; this falls into the category of minor wizardry. And, of course, there is the continuing saga of "The Notebooks of Justin L. Hewser". Prolific writer, that boy. The editor often sighs, and wishes in his heart of hearts that people would write him. Or send articles. Or argue with him about his editorials. It's been a slow month for submissions. I know for a fact that there are programmers who are not on vacation in Florida. If the readership would only smite the keys of their terminals to write articles, they would be much warmer. Now it's time for me to stick in my two cents worth. Yer gettin' a bargain here, folks, it's three cents worth this month at no extra charge. Flame on! .TEST PAGE 5 .SKIP 2 .CENTER ----- Craftsmanship ----- From time to time, I hear purportedly intelligent and experienced computer professionals make remarkable comments on various topics. Sometimes the unexpected magnificence of those comments makes me cringe and want to hide. Most of us have experienced this situation many times. I gladly wager, however, that there are few matches for these classic, untarnished gems of "wisdom" heard recently. The topic is program documentation. .LM +3 .SKIP 2 .INDENT -3 o##"Documentation takes so long to write, you might as well spend the time doing something useful." .BREAK ###(Implication: Documentation isn't useful.) .SKIP .INDENT -3 o##"It's much better to improve interpersonal communication by asking the person who wrote it how it works." .BREAK ###(Implication: Nobody is ever allowed to quit.) .SKIP .INDENT -3 o##"Six months after I've written documentation, I don't understand it, so why write it?" .BREAK ###(Implication: Speaker can't write competently.) .SKIP .INDENT -3 o##"You rarely need to use it anyway, so it's normally wasted time. It's an acceptable risk not to document your programs." .BREAK ###(Implication: Speaker knows nothing about game theory.) .SKIP .INDENT -3 o##"It takes too long to do it, and I just don't want to do it, so I won't." .BREAK ###(Implication: Daddy can't make me do it. Nyaaah!) .LM -3 .SKIP Grrrrrrr! A perceptive observer would have noted my face flush, primary evidence of rising blood pressure. A careful listener would have noted the subdued gnashing of teeth on my side of the table. (And people wonder why I'm so terribly fond of milk of magnesia and aspirin!) The Editor believes in documentation. It has saved his butt more than once. Documentation is a Good Thing, and good documentation should be revered and respected. My opinion is that programmers who do not document are, at best, marginally tolerable subhumans who have learned to bathe, wear clothes, and not make messes in the house. But please don't take my unsupported word as final. Compare the "interesting" (growl!) comments above with Frederick Brooks' comments, extracted from his book ^&The Mythical Man-Month\&: .SKIP .LM +3 .RM -3 "Why have formal documents?" "First, writing the decisions down is essential. Only when one writes do the gaps appear and the inconsistencies protrude. The act of writing turns out to require hundreds of mini-decisions, and it is the existence of these that distinguishes clear, exact policies from fuzzy ones." "Second, the documents will communicate the decisions to others...." "There are those who would argue that the OS/360 shelf of manuals represents verbal diarrhea, that the very voluminosity introduces a new kind of incomprehensibility...." "First ... if one uses it selectively, he can ignore the bulk most of the time." "Second, this is far preferable to the severe underdocumentation that characterizes most programming systems." .SKIP .LM -3 .RM +3 Consider also these comments by Denny Walthers, who is a senior SIG member and an established programming manager. Denny has seen what happens when programs are left undocumented, and offers these remarks in his RSX programming textbook: .SKIP .LM +3 .RM -3 "Documentation starts with the system formal specification. The formal spec should be part of the final system documentation, so the end users can see how well the delivered product stands up against the specified product." "Documentation must be both internal to the code modules and external in the form of a system manual or set of manuals." "Bad documentation is easy to get. Just let your programmers do what they want for documentation. What you will get - if you get anything at all - is a series of printouts of the source code." "Good documentation is harder to get. Getting useful external documentation out of programmers is like pulling teeth without anesthetic; you'd think the act of writing was physically painful." "It is often useful to ^&force\& programmers and first-line supervisors to attend a technical writing course - the resulting improvement is amazing. And if budget allows, a staff "technical" writer can make user manuals readable." "Documentation should be specified in the system design too, and the best rule of thumb is to allocate 50 percent of the time used in coding each module to documentation of that module." "It is easy to let contigencies eat into the documentation time. Don't do it. If you do it once, you will end up doing it again and again, until you have no documentation time left. Documentation is all too often never written because the time allocated to it was used for coding, debugging or what have you. Documentation time is ^&sacred\&." "Note this ^&well\&: Good programmers are mobile, changing jobs every three or four years on average. Without documentation, the expected useful life of your system degrades to (1#/#_##programmers)#*#3. For (_##programmers) greater than 3, then, without documentation you may as well not do the project." .SKIP .LM -3 .RM +3 Very well. Most of us are agreed that documentation is good and useful. It is desirable. It is necessary. But, given the reluctance to write any documentation at all, can production of good documentation ever be assured? In brief - yes. Adhere to the following rules ^&consistently\&, and success is assured: .SKIP 2 .LM +3 .INDENT -3 o##Make documentation required. Allow programmers no choice in writing it. .SKIP .INDENT -3 o##Require all programmers and supervisors to attend a technical writing course. Require a passing grade. .SKIP .INDENT -3 o##Lay down standards for the content of documentation. .SKIP .INDENT -3 o##Require peer review and approval of all finished documentation. .SKIP .LM -3 These rules guarantee your success ^&if\& you adhere to them, with no exceptions. But they sometimes produce this reaction: "Gosh, that sure sounds simple, doesn't it? But everybody at my site is willing to write good documentation, and they're all professionals, so we sure don't need to spend money to send anyone away to learn how to write." In two words - bull, poop. Universities, technical schools and - let's face it - the real world, don't teach people to take responsibility for their work. They ^&do\& teach avoidance of responsibility, and writing documentation is the ultimate assumption of responsibility for one's work. But documenting one's work should be more than assuming responsibility for that work. It is an act of pride, in which the craftsman proudly signs his work, telling the world: "This is mine. I want everyone to know it. I built it, and I have pride in my work." An program left undocumented, on the other hand, shouts to the world that the author is not proud of his work. It may even indicate an author ashamed of his work. It always states clearly that the author is not a craftsman, not a professional peer, and unworthy of admission to the guild hall of master artisans. Document your work. Document it well, and proudly. Be a craftsman. .TEST PAGE 5 .SKIP 2 .CENTER ----- Submitting Articles to the Multi-Tasker ----- Please submit machine readable media when possible. RX01, RX02, RX50, or 9 channel magtape at 800 or 1600 BPI are best. Any RSX/ODS-1 volume format is acceptable except ROLLIN or PRESRV. ANSI, BRU and DOS FLX formats are well-liked by the Editor's tape drive. Submissions which aren't machine readable take longer to get into print. The editor, being lazy, types mass quantities only once a month when progress reports are due. If you preformat a submission in RUNOFF format, please set page size 58,80; left margin 10; right margin 75; and, when changing margins, use incremental changes rather than absolute. The editor blesses you for the consideration. Send all submissions to: .SKIP .NO FILL .NO JUSTIFY Bruce R. Mitchell Machine Intelligence and Industrial Magic PO Box 816 Byron, MN 55920 .JUSTIFY .FILL .TEST PAGE 5 .SKIP 2 .CENTER ----- And That's The Way Things Are ----- _... this month in Pool Lowbegone, where the H960 mounting rails are strong, the 11/70 backplane is good-looking, and the NPR jumper count is above average. .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT DECnet FALLOG SPR .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .TEST PAGE 15 .SKIP 7 .CENTER ^&DECnet FALLOG SPR\& .SKIP ^IS144^GThis article, and the one following, appeared by magic on the Editor's desk one day. My thanks to the contributor. #---#The Editor^IS204^G .SKIP 3 .CENTER Secondary POOL Depletion During FAL Operations .SKIP 2 Problem: During certain DECnet operations involving FAL on RSX-11M-Plus systems, secondary POOL becomes depleted, causing serious system degradation. This problem occurs while wildcard copying from the RSX node to a VMS node, and when a VMS image opens and reads many files on the RSX node. .SKIP 2 Diagnosis: FAL uses secondary POOL to hold file logging records which are eventually passed to the logger task, FALLOG. Observing secondary POOL using RMDEMO while performing the above operations shows that secondary POOL declines steadily. When the operation completes and FAL invokes FALLOG, secondary POOL is recovered. It has also been observed that if the VMS image is aborted and the process stopped, FAL exits on the RSX node without requesting FALLOG. This causes log packets to remain in secondary POOL until completion of the next file operation involving FALLOG. If secondary POOL becomes exhausted, FAL becomes "loop-bound", apparently waiting for more secondary POOL to become available. Although this is the standard "recovery" method for POOL exhaustion, it is unsatisfactory when used by the task causing the POOL problem. .SKIP 2 Solution: FAL's handling of logging packets requires improvement. FAL violates a principal rule of operating systems by assuming that secondary POOL is limitless. Since FAL cannot predetermine how many log packets it will generate, it should periodically request FALLOG to process waiting packets. .SKIP 2 Workaround: Disabling FAL logging avoids the problem. Discovering how to do this was not easy. To disable FAL logging, edit the NETgen parameter file [137,10]DECPRM.DAT. This file is on the DECnet distribution kit. Search for the symbol $DFLLG and set it to false: .SKIP _.SETF $DFLLG Perform a Component Mode NETgen to rebuild FAL, and install the resulting FAL. The new FAL requires no FALLOG. .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT INS and BOO SPR .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .TEST PAGE 15 .SKIP 7 .CENTER ^&INS and BOO SPR\& .SKIP 3 .CENTER Erroneous Error Messages from INS and BOO .SKIP 2 Problem: If an invalid file specification is given to INS, the error message "Task image I/O error" may result. BOO may report "Device offline" under the same circumstances. .SKIP 2 Diagnosis: The FILBN module used by INS and BOO was corrected in Update C of M-Plus V3.0. The .CSI1 routine (CSI$1 macro) branches incorrectly to the "Task image I/O error" handler rather than the "Syntax error" handler. .SKIP 2 Solution: The following correction file to FILBN.MAC corrects the problem. .SKIP 3 .NO FILL .NO JUSTIFY FILBN.MAC;2/AU/-BF=[12,10]FILBN.MAC;1 \ -2,2 .IDENT /7.00/ -4,4 ; COPYRIGHT (C) 1986 BY DIGITAL EQUIPMENT CORPORATION -23,24 ; MODIFIED FOR RSX-11M/M-PLUS V4.1/V2.1 BY: ; ; J. R. KAUFFMAN ; C. B. PETROVIC ; ; LAST MODIFICATION DATE: 24-JAN-86 ; MODIFIED FOR UPDATE C BY: ; ; RMC001 ADD I/O ERRORS, RESPONSE TO SPR #82337 % -152,,/;RMC001/ ; -8 - TASK IMAGE I/O ERROR -248,248,/;RMC001/ BCS 65$ ; SYNTAX ERROR -302,302,/;RMC001/ 112$: BR FNDIOR ; NO, I/O ERROR -349,,/;RMC001/ FNDIOR: MOV _#-8., R1 ; TASK IMAGE I/O ERROR BR FNDERR / .JUSTIFY .FILL .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT Modifying RSX CLI Prompts .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .TEST PAGE 15 .SKIP 6 .CENTER ^&Modifying RSX CLI Prompts\& .SKIP .CENTER Rick Sharpe .CENTER Toledo Edison .CENTER Toledo, OH .SKIP ^IS144^GThis is a update of an article by Don Jensen of Lake County Public Water District. The original appeared in the November 1983 Multi-Tasker. #---#The#Editor^IS204^G .SKIP 2 Many production RSX systems co-exist with other computer systems. In such environments, it is often impossible to have dedicated terminals for each computer system. Instead, terminals are shared between computer systems by manual or electronic switching. When terminals are shared between systems, users often have trouble deciding which system their terminal is connected to. Because entry of invalid commands on a system can have unexpected or disastrous results, it is important for users to know their host system. While experienced users can use RMD, DEV or other means to find out what system they're on, this is impractical for most front-line workers. A quick and certain method of knowing the host system is desirable. Changing the command line interpreter (CLI) prompt is a practical way of identifying the host system to all terminals connected to it. Every time the user gets a CLI prompt, he is reminded that he is connected to system (x). Changing CLI prompts for DCL or RMT isn't difficult - it can be done at system startup time. MCR can be difficult for novice system managers, however, because changing its prompt demands a small patch in the Executive. Fortunately, this patch isn't difficult, and here's how to do it. Before proceeding, however, note well: Caution!# Apply this patch ^&only\& to virgin, unSAVed systems! .HL 1 Find the CLI Prompt Table Address If you have a copy of the Executive map file from SYSgen, examine it to find the symbolic value $CPTBL. $CPTBL is the CLI prompt table pointer. Make a note of its value. If you run Micro/RSX, or do not have a copy of the Executive map file, you can still get the necessary information. Taskbuild LB:[1,54]RSX11M.STB, the Executive symbol table. The resulting map contains a symbol table listing. In the example below, the value of $CPTBL is 053716. .SKIP .NO FILL .NO JUSTIFY X.TCB 000026 $BCPC 001570 $CPMSK 053656 $DDSHD 053274 X.TRCK 000030 $BILDS 033630 $CPNIT 030044 $DEACB 014402 X.UHVR 000037 $BILNG 002133 $CPTBL 053716 $DEAC1 014442 X.UNFL 000002 $BLKCK 023560 $CPUER 001470 $DEAGF 050472 X.UNIT 000054 $BLKC1 023574 $CPURM 053656 $DEARG 040234 .JUSTIFY .FILL .HL 1 Find the CLI Prompt Table Build a new virgin copy of the system image as you would after a normal SYSgen. Boot the virgin image. Use the MCR OPEn command to open the Executive at the address given by $CPTBL. On systems supporting I/D space, open the Exec /KNLD (kernel D-space). In the text following, italics indicate user input: .SKIP .NO FILL .NO JUSTIFY ^IS144^GOPEN 53716/KNLD^IS204^G 00053716 /053756 ^IS144^G^IS204^G .JUSTIFY .FILL The value at location 53716 is a pointer to the first active CLI prompt/control block. In the example above, the value is 53756. Make a note of this value. .HL 1 Find the CLI Prompt/Control Block Open the Executive at the CLI prompt/control block address just found. The CLI prompts are stored about six words "upstream" from this address. Find the CLI prompts, and make a note of their address. You'll need to hand translate the octal words to ASCII. In the example below, the CLI is MCR, the prompt is "> ", and the control-C prompt is "MCR>". .SKIP .NO JUSTIFY .NO FILL ^IS144^GOPEN 53756/KNLD^IS204^G 00053756 /117134 ^IS144^G^IS204^G 00053760 /050712 ^IS144^G^IS204^G 00053762 /000000 ^IS144^G^IS204^G 00053764 /000004 ^IS144^G^IS204^G 00053766 /003405 ^IS144^G ASCII contents^IS204^G 00053770 /005015 ^IS144^G ^IS204^G 00053772 /020076 ^IS144^G > ^IS204^G 00053774 /006400 ^IS144^G ^IS204^G 00053776 /046412 ^IS144^G M^IS204^G 00054000 /051103 ^IS144^G C R^IS204^G 00054002 /000076 ^IS144^G > ^IS204^G 00054004 /171000 ^IS144^G^IS204^G .FILL .JUSTIFY There should not be more than one CLI prompt/control block on a virgin system. .HL 1 Changing the Prompt The locations containing the CLI prompts are modified using OPEn. Continuing with the example above, let's say that we have decided to change the "> " prompt to "] ". The value at location 53772 must be changed to 20135 (high byte 40, low byte 135). .SKIP .NO JUSTIFY .NO FILL ^IS144^GOPEN 53772/KNLD^IS204^G 00053772 /020076 ^IS144^G20135^IS204^G 00053774 /006400 ^IS144^G^IS204^G .FILL .JUSTIFY .HL 1 SAVing the System The procedure above changed the virgin system image, so only now it is safe to change the new system image. Save the system with a SAV#/WB command as you normally would. After completion of SAV, the system has a new, permanent, unique prompt. Users need only see what the prompt is to determine which system they are using. .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT The Notebooks of Justin L. Hewser .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .TEST PAGE 15 .SKIP 6 .CENTER ^&The Notebooks of Justin L. Hewser\& .SKIP .CENTER Jim Bostwick .CENTER Cargill, Inc. .CENTER PO Box 9300 .CENTER Minneapolis, MN###55440 .SKIP This month continues our series of articles based on the personal programming notebooks of Justin L. Hewser. We all know Justin: his work has been seen in every programming shop. The desk in the corner, right next to Murphy. Yeah, him. Justin is a prolific programmer, and we have all at one time or another been forced to work with his product. Forced, because we'd sooner do an spelling checker in APL than look at his stuff voluntarily! This month's note is from the MACRO section of the Notebooks, although it applies equally well to most languages. It presents Justin's solution to the common programming problem of synchronizing access to a shared resource through a global event flag. .SKIP 2 .LM +10 .RM -5 ^IS144^G*M109. -- EFN Synchronization .SKIP Use global event flags to synchronize file access. Each program looks at the flag, and sets it to indicate the file is locked. .NO FILL .SKIP EFN=1 10$: SETF$S _#EFN ; Set the flag CMP _#IS.CLR, $DSW ; Was it clear? BNE 10$ ; No, try again < do your thing here> CLEF$S _#EFN ; Release lock .FILL .SKIP The program tries to set the lock flag. If it was clear, you have it. Otherwise, someone else has set the lock, and you must wait. When it clears the flag, your set returns "IS.CLR" indicating that it was clear, and you know YOU have set the flag.^IS204^G .LM -10 .RM +5 .SKIP The margin notes for this trick indicate random system crashes, also "Don't use this if you don't have to". I'm not surprised. Justin obviously found out that the directive status word tells you the former status of an EFN following a set or clear directive. What he did with this tidbit might be described as massively awesome. Where shall we begin? The program using this is a total pig. Not only does it twiddle its fingers tight looping while waiting for the lock to release, it gets RSX twiddling its fingers, too! Furthermore, because Justin only looks for a specific DSW return code, a coding or runtime error goes undetected. Worse, the program logic jumps right back and does it again, probably repeating the error. The funny thing is, if there are no errors, this bit of code can actually work: only one program can successfully transit the event flag to the set state. What it does to the system is another story altogether. Possibly Justin's system didn't really crash, but just came to a grinding halt from the combined effect of several programs spinning on the $SETF directive. The correct way to implement this kind of lock is to invert the sense of the event flag. You can then use a WTSE$ to put the program to sleep until the resource is available. Be sure to repeat the CLEF$ directive when you wake up - someone else may be competing for access, and you must guarantee that ^&your\& program cleared the flag, and not some other. For example: .NO FILL .SKIP 2 10$: CLEF$S _#EFN ; Try for lock BCS ERROR ; My error handler CMP _#IS.SET, $DSW ; If eq, we got the lock BEQ 20$ WTSE$S _#EFN ; Wait for unlock BCS ERROR BR 10$ ; Bid for lock again # 20$: ... code continues .FILL .SKIP We might use $STSE rather than $WTSE to put sleeping tasks in the stopped state rather than wait-for state. A stopped task checkpoints at zero priority, while a waiting one checkpoints at normal run prioriry. The choice between stopping and waiting depends upon how long the task intends to wait to gain access. If it will be a "long" time, use $STSE. If the delay will be "short", use $WTSE. Another requirement with this code is a guarantee that the flag will eventually release. Doing this rigorously is easier said than done. A successful compromise is to set a mark time ($MRKT) for some reasonable period as soon as the lock is set, specifying an AST completion routine. Cancel the marktime when the lock is released. If the AST ever fires, do something useful in the AST service routine. This whole mechanism is wrapped up in a 'lock' and 'unlock' pair of subroutines, with error handling and optionally timeout support. Aside from the timer support, you can do the whole thing in your favorite HLL (FORTRAN or whatever) if you don't like MACRO. There is certainly a wealth of information in Justin's notebooks. I have only begun to analyze them in detail. Here are some candidates for future columns: .SKIP o##Emulating TECO with EDT Keypad Macros .BREAK o##System Programming in DIBOL-11 .BREAK o##Fast Fourier Transforms in Datatrieve