.NONUMBER .LM 0 ^PY^- .PAGE SIZE 58,85 .LM 10 .RM 75 .NO FILL .NO JUSTIFY # .SKIP 5 ^IC0000^IS328^GThe RSX Multi-Tasker^IS204^IC1000^G .SKIP ^IC0000^IS328^GSeptember, 1987^IS204^IC1000^G .SKIP .CENTER ^IS144^G"Cujo?"^IS204^G .SKIP .CENTER Fine Realtime Commentary Since 1975 .SKIP 6 .CENTER ^&Table of Contents\& .SKIP 2 .TAB STOPS 65 Food for Thought RSX-1 The Editor's Corner RSX-1 ADA and VAXes and Pigs RSX-2 Submitting Articles to the Multi-Tasker RSX-3 And That's The Way Things Are RSX-3 Bulletin Board Notes RSX-3 Erratum: Security of the RSX-11 Operating Systems RSX-4 The Hitchhiker's Guide to RSX, Part II RSX-6 .JUSTIFY .FILL .SKIP 15 .LM +5 .RM -5 Opinions expressed in the editorial section of the Multi-Tasker are those of the Editor. They do not represent the official position of the RSX SIG or that of DECUS leadership in general. .LM -5 .RM +5 .PAGE .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT Food for Thought .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT # .SKIP 7 .AUTOPARAGRAPH #######################^IC0000^IS328^GFood for Thought^IS204^IC1000^G .SKIP "They must have procedures for when the computer goes haywire. ... Sooner or later you come up against human beings. That's the thing about people who think they hate computers. What they really hate is lazy programmers." .SKIP 2 .INDENT 30 ^IS144^G- Larry Niven^IS204^G .INDENT 30 ^IS144^G##Oath of Fealty^IS204^G .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT The Editor's Corner .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .SKIP 9 ######################^IC0000^IS328^GThe Editor's Corner^IS204^IC1000^G .SKIP .CENTER Bruce R. Mitchell .SKIP It's been a pretty slow month here at the Multi-Tasker offices. What with bringing up the RSX bulletin board system, trying to figure out why the 11/60 doesn't work, populating the BBS's RAM cards, bringing up a new 11/34, begging hardware for the BBS, prepping for fall term classes, and a few other miscellaneous things, there hasn't been much to do. Too boring! Now, if you believe that, I have this here fine 11/03 that runs M-Plus like a champ. Only used by a grad student on weekends to play Adventure. And I'll throw in the RK03s for cheap. This month, the Multi-Tasker completes serialization of the "Hitchhiker's Guide to RSX". That frees up lots and lots of space starting with the October issue for user written articles, so write 'em up and move 'em out! And a second (!!) erratum to Tom Wyant's article on system security appears. That pretty much fills up this issue. But, in upcoming issues ... Start thinking about the Fall Symposium, because it's coming up pretty soon now. For those of you who have "budget conscious" management - or who think you do - there's an article next month on how to justify DECUS to your management so you can get in on the goodies. And, fair warning: Justin L. Hewser has promised an article on how to do SYSgen good - ^&plus\& how to optimize system performance. I can hardly wait. If I get only a day notice beforehand, I can take a week's vacation and be out of town before the users read it. Keep your peepers peeled for these and other exciting articles. Ha! It's editorial time again. .TEST PAGE 5 .SKIP 2 .CENTER ----- Ada and VAXes and Pigs ----- Rhetorical question: What do ADA, VAXes and pigs all have in common? Choose one of the following responses. There is only one best answer. .SKIP a)##All are general purpose .BREAK b)##All are resource hogs .BREAK c)##All are crammed down your throat If you didn't pick answer (c), turn in your PDP-11 programming card to someone who needs it and go see what kind of funny messages you can get out of VAX/LSE. "We don't need your kind 'round here." Yes - all are crammed down our throats. The Department of Defense crams ADA down our throats by insisting that it's the only possible language for writing DoD software. Both Digital and management cram VAXes down our throats by insisting that they're a universal solution to all computing problems. And as for the pigs - pass the breakfast sausage, please. There ^&is\& a difference, of course. ADA and VAXes are generally crammed down our throats without regard to merit. That's generally not the case with the pigs. But with all the unsolicited "help" we're getting, it's probably a good thing that we can eat our own breakfasts without assistance. Certainly, there are many cases in which ADA and VAXes are appropriate. Equally certainly, there are as many or more cases in which they're inappropriate. But, in either case, cramming them down our throats as panaceae is ^&just plain dumb\&. Support appropriate technology. The next time someone says "ADA" or "VAX" - stick a metaphorical finger down their throat. .TEST PAGE 5 .SKIP 2 .CENTER ----- Submitting Articles to the Multi-Tasker ----- Please submit machine readable media. RK05, RK07, RL01/2, RX01/2, RX50, TK50, 9 channel 800/1600 BPI magtape or paper tape are OK. Any medium I can't read I can get converted; don't let that stop you. All RSX volume formats are acceptable, but I ^&can't\& read VMS Backup or ODS-2 stuff. You can also submit articles through the RSX bulletin board system. Send them via MAIL to username MULTITASKER. Submissions which aren't machine readable may take longer to get into print. The editor is lazy and types mass quantities only once a month when progress reports are due. If you preformat a submission in RUNOFF, 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 your articles and other submissions to the luxurious Multi-Tasker offices: .SKIP .NO FILL .NO JUSTIFY Bruce R. Mitchell Machine Intelligence and Industrial Magic PO Box 816 Byron, MN 55920 (507)#775-6268 .JUSTIFY .FILL .TEST PAGE 5 .SKIP 2 .CENTER ----- And That's The Way Things Are ----- _... this month in Pool Lowbegone, where the forward and backward links are strong, the free list size is good-looking, and the UCB extensions are above average. .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT Bulletin Board Notes .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .TEST PAGE 15 .SKIP 6 ####################^IC0000^IS328^GBulletin Board Notes^IS204^IC1000^G .SKIP The BBS management reports the system is now running fairly reliably after a series of problems in July. A rash of RK07 problems - still ongoing as of this writing - drastically reduced system uptime. As of late July, RSX MAIL and Kermit are available. Conferencing is unavailable but is a high priority. The system still needs hardware. Q-bus, Unibus, Omnibus, MOS RAM, core, I/O, you name it. The biggest needs right now are a couple 80 Mb SMD winchesters and a 2400 baud modem. But anything and everything goes, so pack up your junk and ship it off to the BBS management c/o your friendly Multi-Tasker editor at the address above. The BBS number: 1-612-SPR-PONG / 1-612-777-7664. This line is autobaud Bell 103 (110 - 300 baud) or 212 (1200 baud) protocol. To request an account, log in with account name ACCOUNT, password REQUEST. .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT Erratum: Security of the RSX-11 Operating Systems .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .TEST PAGE 15 .SKIP 6 ###^IC0000^IS328^GErratum: Security of the RSX-11 Operating Systems^IS204^IC1000^G .SKIP .CENTER Thomas R. Wyant III .CENTER E. I. DuPont de Nemours _& Co., Inc. .CENTER Textile Fibers Department .CENTER Richmond, VA###23261 .SKIP A page was somehow left out of the article "Security of the RSX-11 Operating Systems" in the June 1987 issue of ^&The Multi-Tasker\&. (It went in, but wasn't printed!) The missing page should have been between pages RSX-16 and RSX-17. The topic is brute force system cracking. The page follows. .PAGE .CENTER Brute Force Brute force password cracking is unlikely for reasons that will be discussed here. .SKIP RSX-11M RSX-11M and old versions of M-Plus are considered by some to be insecure because of the password shortness - 6 characters. This does not appear to be a serious threat, provided that passwords are chosen "at random" so that there is no way to restrict a search, and all passwords are 6 characters long. To show this, calculation of the time required for an exhaustive search of all passwords less than a given length is in order. Assume that a single password can be tried in one second, using automated equipment. The actual figure depends on several factors (such as line speed and system load), but should not be much less than this. According to the System Management Guide, a total of 41 characters are valid in passwords. Time required to search all passwords less than a given length is then: .SKIP .NO FILL .NO JUSTIFY Ch Paswrds Search Time -- ------- ------------ 0 1 1 second 1 42 42 seconds 2 1723 28.7 minutes 3 70644 19.6 hours 4 2.89E+6 33.5 days 5 1.19E+8 3.76 years 6 4.87E+9 154 years .JUSTIFY .FILL Obviously the average time to find a password is half this, but the numbers are still sufficient. .SKIP 2 RSX-11M+ Current versions of RSX-11M+ allow longer passwords (39 characters) and encrypt the password copy in the account file. As password length increases, the time required to get in by brute force quickly becomes prohibitive, as long as passwords are chosen "at random". However, a user of the brute force method can speed his task considerably if he can obtain a copy of the account file from insufficiently protected backup media. He can generate and encrypt his own passwords and compare the encrypted values to what is in the ... .COMMENT .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT The Hitchhiker's Guide to RSX, Part III .COMMENT +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .COMMENT .TEST PAGE 15 .SKIP 6 #############^IC0000^IS328^GThe Hitchhiker's Guide to RSX, Part III^IS204^IC1000^G .SKIP .CENTER A-to-Z Base Product Marketing .CENTER Digital Equipment Corporation .CENTER Continental Boulevard, MKO1-2/E25 .CENTER Merrimack, NH##03054 .SKIP Through the kind intervention of a Digital employee, the Multi-Tasker is pleased to present "The Hitchhiker's Guide to RSX". This is probably the best overall coverage of the current RSX environment available. It is also a valuable reference for all application programmers, not just business application developers. This document is being serialized due to its length. This is the third of three parts, covering chapters 9 through 12. .PAGE # .SKIP 6 .CENTER HITCHHIKER'S GUIDE TO RSX .SKIP 2 .CENTER An Introduction to RSX for Business-Application Developers .SKIP 6 .CENTER Revision 0.0 .SKIP 4 .CENTER Disclaimer .SKIP This is a preliminary version and is not quite one-hundred percent complete. Please send comments, questions, and recommendations -- on this document -- to A-to-Z Base Product Marketing, MKO1-2/E25, Digital Equipment Corporation, Continental Boulevard, Merrimack, New Hampshire 03054. .SKIP The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. .SKIP The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such license. .SKIP No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. .SKIP 3 .CENTER Copyright (C) 1986 by Digital Equipment Corporation .CENTER All Rights Reserved. .CENTER Printed in U.S.A. .SKIP 2 .CENTER September, 1986 .PAGE .CENTER Table of Contents .SKIP 2 .NO FILL .NO JUSTIFY Chapter 9 Linking and Overlays 9.1 Invoking TKB 9.2 Disk Overlays 9.2.1 Trees 9.2.2 Co-Trees 9.3 Memory Resident Overlays 9.4 Guidelines for Use 9.5 Linking to RMS 9.5.1 Disk Resident RMS 9.5.2 Memory Resident RMS 9.5.3 Clustered RMS 9.5.4 Supervisor Mode RMS 9.6 Useful Options 9.6.1 Privilege 9.6.2 Task Priority 9.6.3 Task Name 9.6.4 Cross Reference Map Chapter 10 Packaging Applications for RSX 10.1 Kitting for Micro/RSX 10.1.1 Micro/RSX Layered Product Installation Architecture 10.1.2 Creating the Kit 10.1.3 Developer's Note 10.2 Kitting for M-Plus 10.3 Kitting Applications for A-to-Z Chapter 11 System Operation 11.1 Terminals 11.1.1 CLI 11.1.2 BROADCAST 11.1.3 CONTROL=C 11.1.4 INQUIRE 11.1.5 FULL_DUPLEX 11.1.6 ESCAPE 11.1.7 EIGHTBIT 11.1.8 HOSTSYNCH 11.1.9 SERIAL 11.1.10 SLAVE 11.1.11 LOWERCASE 11.1.12 WRAP 11.1.13 TYPEAHEAD 11.2 Partitioning Memory 11.2.1 Exec and Primary POOL 11.2.2 Secondary POOL and Extension 11.2.3 Task Space 11.2.4 Cache Region 11.3 Disks 11.3.1 Initializing 11.3.1.1 Preparing a Disk 11.3.1.2 Initializing a Volume 11.3.2 Mounting 11.3.3 Dismounting 11.4 Creating Directories 11.5 Files 11.5.1 File Performance 11.5.2 File Protection 11.6 Logical Names 11.7 Disk Caching 11.8 Printers and Queues 11.8.1 Queue Mechanism 11.8.2 Submitting Jobs 11.8.3 Startup 11.8.4 Shutdown 11.8.5 Transparent Spooling Chapter 12 Troubleshooting 12.1 Before You Start 12.2 Diagnostic Tools 12.2.1 Resource Monitor Display (RMD) 12.2.1.1 Memory 12.2.1.2 Active Task Display 12.2.1.3 Task Display 12.2.1.4 I/O Counts Display 12.2.1.5 System Statistics 12.2.1.6 Cache Region Display 12.2.1.7 Detailed Cache Statistics 12.2.2 Error Logging 12.2.3 Resource Accounting 12.3 What to Look For 12.3.1 Disk Saturation 12.3.2 Insufficient Memory 12.3.3 Unbalanced Load 12.3.4 Insufficient POOL 12.3.5 File Contention 12.3.6 Low Cache Hit Rates 12.3.7 Insufficient Checkpoint Space 12.3.8 Excessive File Opens 12.3.9 Overloaded Directories 12.3.10 Jobs at Wrong Priority 12.3.11 Misuse of Batch .JUSTIFY .FILL .PAGE .CENTER Hitchhiker's Guide to RSX .SKIP .CENTER D O N ' T P A N I C .SKIP 3 .CENTER Chapter 9 .SKIP .CENTER Linking and Overlays .SKIP 2 Probably the single biggest surprise to developers who are moving to RSX from other environments is the linker - the infamous Taskbuilder, TKB for short. It's very, very slow. We know it's slow, we use it too. There's no getting around it. No matter which implementation language you choose, sooner or later you have to deal with the Taskbuilder. It's also an exceptionally powerful linkage editor. With it you can form your program into a monolithic or overlaid structure, hook in shared common regions, set execution priority, pre-open I/O channels, make use of Supervisor Mode shareable libraries, patch global references, set stack sizes, even get cross reference tables. If your language allows, you can create multi-user (shareable) task images. You can even arrange that disk overlay segments be loaded asynchronously. The cost of all this functionality is that the Taskbuilder itself executes very slowly compared to RT-11 or VMS. Again, this section is not intended to make you an expert but rather to get you started as quickly and as easily as possible. See your language RSX User Guide for further details. .SKIP 2 9.1##Invoking TKB TKB commands and parameters can be entered interactively but, for any but the simplest programs, you find it much easier to use it with command and map files. The Command file (.CMD) contains the input and output file specifications and all the option statements. The Map file (.ODL) describes the location of the object files and the manner in which they are to be arranged and/or overlaid. If an ODL file is to be used the name of the file is supplied in the CMD file in place of the list of input modules. Most of the high level languages (DIBOL, BASIC, COBOL) have a "build" option of some type which constructs prototype CMD and ODL files for you. The CMD files can often be used as is. Unfortunately, it is not possible for the various compilers to anticipate the way your subroutines call each other, so it is left to you to design and describe the module overlay structure, and edit the ODL file accordingly. .SKIP 2 9.2##Disk Overlays As an application designer you may choose from a number of options with regard to overlays. You may use a single overlay tree structure or you may use multiple, co-trees. You may specify that the overlay segments be loaded manually or automatically. You may direct that the overlays be loaded from disk or be mapped from memory. Overlaying subroutines from disk on RSX is done as on most other systems - a call to an entry point in the routine is actually diverted to a system (linker) supplied autoload vector which checks first to see if the segment is already loaded and if not, issues a read request to the program image on disk to load the blocks which contain the desired routine. Once the routine is loaded into the proper address range, the call is allowed to complete. Note that this mechanism is only intended to work for a call. Attempting to reference data in overlay segments generally does not work unless you load the segment manually. Overlay segments may be specified as manual load or autoload. Only the latter mechanism is of interest to most commercial application developers. .SKIP 2 9.2.1##Trees TKB requires that overlays be strictly tree structured, that is, the main program module forms the root or trunk of the tree and the subroutines are grouped into segments which form the branches. When a module which is lower in the tree calls a module which is higher up, the intervening segments are also loaded into memory. Subroutines may not call each other across branches, and TKB assures that global symbols are resolved uniquely in each path of the tree. Thus, if routines in two or more branches of the tree call a common routine, and that routine is not linked into the root (routines in the root are always available to be called from everywhere), then there may be two or more copies of the routine in different places in the task image on disk. If such a single tree structure is used, TKB assures that the references throughout the tree are correct and proper. It is, in fact, searching up and down the branches of the tree to assure that there are no ambiguities in the intercall structure and that return paths are always protected, that consumes much of the execution time of the Taskbuilder. .SKIP 2 9.2.2##Co-Trees Developers who are used to other sorts of overlay structures, such as the regions used on RT-11 may find that task images become monstrously large due to the requirements for unique pathways and hence duplication of code many times throughout the structure. It may, in fact, be impossible to attain certain kinds of functionality, particularly if subroutine context is expected to be maintained across calls to the routine. In such a case you may use co-trees to emulate the RT-11 region structure. To do this, you define multiple root segments, one for the root segment and one for each "region". The modules which are to reside in each region are then linked to the appropriate root. These extra root segments may contain application code or they may be dummy (null) segments created with NAME directives in the ODL file. Co-trees allow a much greater degree of flexibility in terms of calling segments from different parts of the program and following different paths to a common routine. However, it is impossible for the Taskbuilder to determine in what order calls occur, and there is no protection against calls which might cause the return path to be destroyed. The following (oversimplified) command sequence directs the RT-11 linker to create a program with a root and two overlay regions. MAIN can call any of the four subroutines directly and the routines can call each other as long as the return path is preserved. .SKIP 2 .NO FILL .NO JUSTIFY PROG=MAIN/C SUBRA/O:1/C SUBRB/O:1/C SUBRC/O:2/C SUBRD/O:2 .JUSTIFY .FILL .SKIP 2 This (oversimplified) ODL structure directs the Taskbuilder to create an overlay structure which is functionally identical to the one shown above. .SKIP 2 .NO FILL .NO JUSTIFY ########.ROOT MAIN-REG1-REG2 ########.NAME NULL1 REG1: .FCTR NULL1-*(SUBRA,SUBRB) ########.NAME NULL2 REG2: .FCTR NULL2-*(SUBRC,SUBRD) .JUSTIFY .FILL .SKIP 2 The RT-11 overlay regions and RSX co-trees are so similar that translation from one to the other is almost entirely mechanical. .SKIP 2 9.3##Memory Resident Overlays Memory resident overlays work by changing the virtual address mapping registers for the task. When the program is initially loaded into memory, the entire task image is loaded from disk. When a call to an overlay segment takes place, the call is once again diverted to the autoload vectors, only in this case the segment load is accomplished by changing the memory management mapping control registers so that the subroutine "appears" in the correct place. Since there is no wait for the disk transfer to complete, the overlays are much faster. There are, however, a number of restrictions. Because of the way the memory management hardware works the memory resident overlay segments must begin on 8 KB memory boundaries and the segment size may not exceed 8 KB. Also, the Taskbuilder locates the overlay segments in such a way that the task "upper limit" cannot be extended in memory. The former restriction is a nuisance but the latter is more severe, particularly for language processors which allocate "heap" storage dynamically. Of the popular languages on PDP-11s, only Fortran allows the use of memory resident overlays. The use of disk data caching in RSX V3.0, however, improves the speed of disk overlays to almost that of memory resident. .SKIP 2 9.4##Guidelines for Use Overlays do not come free. Even memory resident overlays require a fair number of machine instructions to be executed. Therefore, if overlays are misused there may be a problem with performance. In particular: Disk overlays are just like any other kind of disk I/O. There is a delay while the autoload code waits for the QIO to complete and there is an opportunity cost when the disk head is moved away from the data files. You should carefully consider the flow of control through your subroutine structures. The best possible design is where the flow is sequential through a series of segments in the same region with each performing its particular function in turn. Many application root segments are nothing more than a common data region for context and a series of calls which invoke a stream of modules moving through the segment. The worst possible design is one in which two, co-resident routines are called repetitively. There was a case in which the keyboard input and output routines of a program occupied the same region but were in different segments. Every time the operator pressed a key there were at least two disk read operations. The performance of the application doubled when these two routines were moved to the root. .SKIP 2 9.5##Linking to RMS RMS is provided in the form of one or more subroutine libraries which are, insofar as is possible, language independent. All of the high level language compilers translate the various I/O statements into a call to one of the RMS routines and provide such mapping of arguments as may be required for proper communication. The first version of RMS was nothing more than a collection of object modules which had to be linked directly to the application program. As hardware and software technologies improved it became possible to shortcut many of the linkage processes while at the same time improving task sizes, linking time and processing speed. RMS is provided in several different forms and each has its own linkage method. You must select the flavor and the linkage when you task build your program. You may chose between a variety of linkages, usually without changing any aspect of your application code. .SKIP 2 9.5.1##Disk Resident RMS It is still possible to link the RMS modules directly to your program. The code is quite large, however, and arranging a suitable overlay structure may become burdensome. Unless you have very special requirements you should select the clustered library. .SKIP 2 9.5.2##Memory Resident RMS RMS is provided in a special library which uses memory resident overlays to keep the virtual program space requirements to a minimum. When you use this form you actually link only a stub routine into your program. This stub intercepts the calls to the various RMS routines and causes the appropriate RMS segment to be mapped into your program space. The RMS code itself is stored in a special library which must be independently installed on your system. Since you are only linking to the RMS stub the link process itself is much faster. This form of RMS is considerably faster than the disk overlaid version since the RMS segments are shared between all applications and are usually already in memory. All of the disk overhead associated with the RMS overlays is eliminated. Use of this library also has the advantage that there is only one copy of the RMS code on the system. This results in a very great savings of space required to store task images. Finally, it means that the system manager can upgrade to a newer version of RMS by simply replacing the common library. There is no need to re-link all the application programs. You select this form of RMS by including a LIBR declaration in your CMD file and a pointer to one of the secondary RMS ODL files in your primary ODL file. The RMS library uses two of the eight memory segments your task is allowed, thus consuming 16KB of address space, about what the full, disk-overlaid version requires. .SKIP 2 9.5.3##Clustered RMS Most languages require a run-time library of some sort and, in most cases, this library is similar to the memory resident form of RMS. Since RMS requires 16KB and most of the language libraries require a similar amount this limits your program space to 32KB total. It is possible, however, to cluster the language and RMS libraries in such a way that they occupy the same virtual addresses so that the available program space is increased to 48KB. You direct the Taskbuilder to cluster RMS and the language library by replacing the LIBR statement in the CMD file with a CLSTR statement. This is the default for most of the Build options in the language processors. .SKIP 2 9.5.4##Supervisor Mode RMS Memory resident overlays are considerably faster than disk overlays and they certainly reduce the amount of disk head contention on the system, but they still consume CPU time. On processors which support supervisor mode RMS may be linked as a supervisor mode library. This option causes RMS to use two otherwise idle Address Page Registers (APRs) and reduces the time required for context switching between the RMS and language libraries. You specify supervisor mode RMS by changing the LIBR or CLSTR statement in the CMD file to RESSUP and making certain explicit references to special RMS modules in your ODL file. See the RMS-11 User Guide for details. .SKIP 2 9.6##Useful Options The Taskbuilder offers several useful options to the developer. These options are invoked with statements in the CMD file. .SKIP 2 9.6.1##Privilege In the early versions of RSX a privileged task was one which was mapped directly to the Executive and could read and write the various data tables and structures. Privileged tasks are also exempt from the system security mechanisms and can read, write, modify and delete files regardless of ownership or protection codes. It is now possible to build a privileged task which does not map to the Executive but which can bypass file protection. You can use this technique to permit a user to perform occasional privileged operations. To taskbuild a privileged program, append the /PR:0 switch to the task filespec in the CMD file. Privileged tasks can create severe gaps in system security, so be careful when writing them. .SKIP 2 9.6.2##Task Priority You may be able to improve the overall crispness of your application by adjusting task priorities. You may modify a task priority when you install it or when you run it, but you may wish to set the normal operating priority with the Taskbuilder. You may specify a task priority with the PRI=nnn option. Priority may range from 1 through 250 with higher numbers indicating higher priority. Normal system priority is 50. .SKIP 2 9.6.3##Task Name .SKIP 2 You can set the task name with the TASK=name option in the CMD file. This is the most convenient way to set a task name to other than the task file name. It is also a convenient way to specify a prototype task name. .SKIP 2 9.6.4##Cross Reference Map You can direct the Taskbuilder to append a Cross Reference table to the map file. This table shows where all the global entry points (usually subroutine names) are defined in your task and where they are referenced. This option is particularly useful when you are restructuring your overlays or trying to locate typographical errors in CALL statements. You request this table by appending the /CR switch to the map filename in the CMD file. The Cross Reference Facility (CRF) must be installed on your system for this to work properly. .PAGE .CENTER Chapter 10 .SKIP .CENTER Packaging Applications for RSX .SKIP 2 There are two views of layered product installation: That of the person performing the installation and that of the developer who is constructing the distribution kit. The former is discussed in the section on Getting Started with RSX. This section outlines what a developer must do to package an application for installation on a production system. The layered product developer is responsible for creating the distribution kit - media and documentation - that enables the system manager to install the software as quickly and easily as possible, and with the desired level of functionality. The kitting process takes two forms according to whether the target system is Micro/RSX or M-Plus. .SKIP 2 10.1##Kitting for Micro/RSX Creating a software option for Micro/RSX is easier if the developer understands something of the underlying architecture. .SKIP 2 10.1.1##Micro/RSX Layered Product Installation Architecture Micro/RSX was designed with the naive user in mind. A command procedure supplied with the system controls installation and removal of all layered products. This means that the developer is responsible for packaging the application so that the command procedure operates correctly. When the installation control file (OPTION.CMD) is invoked, it mounts the media on the drive selected by the user and looks in directory [0,0] for a file INSTALL.DAT. This file is provided by the developer and contains certain information about ALL options on the media set including the name of the option and a pointer to the installation parameter file for the layered product. The installation parameter file is also provided by the developer. It contains information about files comprising the application, where they go on the target system and whether they are to be deleted when the option is removed. It also contains directions for actions that must take place during installation, during system startup, and during removal. There are conditional mechanisms by which the installation can be modified if, for example, floating point hardware is available or I/D space is supported by the CPU. .SKIP 2 10.1.2##Creating the Kit The kit is nothing more than an image of the application as it resides on the target system. If a file name APPL.XYZ is to be placed into directory [POOF] on the system then it is stored in a directory with the same name on the kit. When the application is installed, the appropriate directories are created as needed. The simplest case is diskette distribution media. The developer initializes enough diskettes to contain the product, creates directories and copies files into place, just as they are on the customer's system. The developer then creates the INSTALL.DAT and installation parameter files and adds them to the disk set. Creating a kit for magtape distribution is approximately the same except that instead of creating an image of the application on disk, the files are distributed as a collection of backup save-sets. The INSTALL.DAT and parameter files are placed in a special save-set at the beginning of the tape. It is usually easiest to develop and debug an installation using disks as media and then convert the procedure to magnetic tape. The conversion from disk to tape kits is largely mechanical. .SKIP 2 10.1.3##Developer's Note Underlying this automation is a database of interest to the developer, especially during the debugging of the installation procedures. A list of all the software options installed on a system is kept in the file LB:[1,2]OPTIONS.DAT. You can examine and modify this file with your favorite text editor. Each record contains the name of an application and a pointer to the installation parameter file for that application. If OPTIONS.DAT is deleted or corrupted, the layered product database is destroyed and must be rebuilt, usually by deleting all the application files and starting over. Under certain conditions (noted below) OPTIONS.DAT is examined during system startup and the various parameter files are opened and scanned for any actions which must be performed. The scanning process is slow, so as the actions are performed they are also collected in a shortcut startup file LB:[1,2]FASTART.CMD. FASTART.CMD is the key to system startup. If it exists during startup, it is executed directly, since doing so is much faster than parsing the different layered product installation parameter files. If FASTART.CMD does not exist, it is rebuilt from information in OPTIONS.DAT. Removing a software option from the system is one way this file might be deleted. Since parsing of the application installation parameter files is slow, a system startup after an application is removed takes considerably longer than normal. There are conditions, such as a product installation which aborts, in which the contents of OPTIONS.DAT and FASTART.CMD no longer match and the system may begin to malfunction. The cure for this is to edit OPTIONS.DAT to assure that the contents are as desired. Then delete all versions of FASTART.CMD and restart the system. FASTART is built anew during the subsequent startup. .SKIP 2 10.2##Kitting for M-Plus Creating a layered product for M-Plus is largely a matter of collecting all the components and creating a command file which controls the installation procedure. The Indirect Command File processor (IND) on RSX provides extensive and detailed access to the underlying system and it is rare that a layered product has any installation requirements which cannot be satisfied with IND. It is now fashionable to design the kit in such a way that the installer need only copy the INSTALL.CMD file into a temporary directory and invoke IND to execute it. Writing IND procedures is no more difficult than other kinds of programming but, like all implementation languages, it has a flavor and style of its own. If you have access to any layered products you may wish to examine a copy of the INSTALL.CMD and possibly even use it as a starting point. When creating this command file the developer must consider the spectrum of hardware and software configurations upon which the product is to be supported. If any tasks require access to the system Executive and/or data base they may need to be linked on the target system. Provide the required object modules (in a library for convenience) and the command and ODL files, and link the task during installation. The command file should be structured with as much of the dialog as possible up front so that when it is complete the more lengthy operations can proceed without further intervention. You should provide for errors during installation and, where it is not possible to recover, provide a means by which the installation can be unwound and the system restored to its original state. Documentation for the manager should not only describe the average conditions under which the product is supported but should also explain enough of the overall architecture that a knowledgeable system manager can tailor the product to an unusual configuration. You should provide information about the consequences of the different alternatives at each choice point. You should also provide whatever information the manager needs to modify the system startup file to create the proper environment for your product. At the least, provide a system startup command file fragment which can be inserted by the manager. Creating a disk kit is straightforward. Initialize the disk and create as many directories as are required with whatever structure is most convenient. Your command file can then copy the files into the appropriate place on the target system. Magnetic tape is a little trickier since it is a strictly sequential medium and since there is a certain difficulty with unusual types of files. The most commonly used magnetic tape transfer utility is FLX which is rather like a PIP designed specifically for magtape. Once your disk installation is working to your satisfaction you can create a magtape kit by putting together a command file which invokes FLX to copy all the necessary files onto the tape, usually with the INSTALL.CMD file going first. It is important to match the order of the files on a tape with the order in which INSTALL.CMD attempts to copy them onto the target system. If the files are in order (even if some of them get skipped), the No-Rewind switch can be used with FLX to greatly reduce the time spent searching along the tape for the next file. There are two problems which are frequently encountered with FLX. The first is that there is no concept of file contiguity on magnetic tape so contiguous files, particularly task images, must be accorded special treatment. The FLX command to copy the task image to the target disk must not only specify that the output file be contiguous but must also specify an initial allocation. This allocation must be the actual size of the image in blocks so it is necessary to update INSTALL.CMD anytime a task size changes. The other problem with FLX is that files with certain types of contents, such as message files, cannot be transferred. The only way around this is to convert the file to a simpler format before building the kit, and transfer the source file and any necessary commands or parameters for converting it back to the desired format once it's on the target system. You can make use of the temporary directory for such operations. .SKIP 2 10.3##Kitting Applications for A-to-Z A-to-Z was designed to be installed on Micro/RSX and has extended the architecture to provide mechanisms by which a layered product can update the A-to-Z database and integrate itself into the A-to-Z environment. A-to-Z has more recently been made available on Pregenned and full M-Plus, and carries with it a variation of the Micro/RSX layered product installation. This makes it much easier for a naive system manager to install and manage an application mix. It is also easier for product developers, since the kitting procedure for A-to-Z applications on Micro/RSX and M-Plus is the same. Only the media are different. .PAGE .CENTER Chapter 11 .SKIP .CENTER System Operation .SKIP 2 Once your application is modified to take full advantage of the features of RSX, you may turn your attention to the details of the underlying system. It is important to tune the application first, since a job mix which misuses the underlying system or which consumes an inordinate amount of resources makes it difficult if not impossible to attain a satisfactory level of performance no matter how much effort is put into the system. This section describes the various dimensions along which you can tailor RSX for a commercial application environment. This section is not intended to be comprehensive but rather to get you started as quickly as possible. Consult the RSX Command Language Manual and the System Management Manual for more details. .SKIP 2 11.1##Terminals Traditionally, RSX is oriented towards expert operators who require only the barest assistance or prompting from the Command Line Interpreter. The terminal driver reflects this heritage and developers who are moving to RSX from other operating systems may be startled by some of the default terminal characteristics such as being able to submit multiple commands for parallel processing by the operating system. Terminal characteristics are most commonly set during system startup. On Micro/RSX and Pregenned M-Plus the terminal attributes may be set with suitable statements in SYSPARAM.DAT. On M-Plus you may include SET TERMINAL/attribute commands in STARTUP.CMD. You may also set terminal attributes as part of the user's LOGIN.CMD. A-to-Z offers a comprehensive terminal management architecture which you may wish to use in place of individual system tailoring. The following list of terminal attributes may be set or cleared with the DCL SET TERMINAL/attribute command. This list is not inclusive but contains the terminal settings which are typically of importance on a commercial system. See the RSX Command Language Manual for further details. .SKIP 2 11.1.1##CLI You may set or change the CLI attached to a terminal. Most commercial people prefer DCL. A default CLI is set when you create the account, but there may be circumstances under which you wish to change the CLI for some special purpose. .SKIP 2 11.1.2##BROADCAST Terminals which are set /BROADCAST are subject to message delivery when messages from a BROADCAST command arrive. This may disrupt information on the screen but the message may be important enough that this is acceptable. Certain messages, such as those issued during the last five minutes of SHUTUP cannot be intercepted. Setting of this attribute is left up to the developer. .SKIP 2 11.1.3##CONTROL=C This attribute determines whether typing CTRL/C at the keyboard aborts any program currently in progress at the terminal. If the terminal is set /NOCONTROL=C, typing CTRL/C allows any ongoing task to continue while the operator enters another command to the CLI. This is the means by which you may invoke multiple tasks simultaneously. The recommended setting for users in a production environment is /CONTROL=C. .SKIP 2 11.1.4##INQUIRE Using the /INQUIRE attribute in a SET TERMINAL command causes the operating system to send the Request Device Attributes escape sequence to the terminal and then to listen for an identification string. If the response from the terminal is one of the DEC supported terminals then the terminal type is set accordingly. This attribute is useful when the terminal type on a particular line might change from time to time such as when a LAN is in use. You may override the terminal type setting at any time with the SET TERMINAL/type command where type is one of VT100, VT200, etc. .SKIP 2 11.1.5##FULL_DUPLEX Terminals set /FULL_DUPLEX may accept input and receive output at the same time, and allow overlapping terminal input and output requests for languages which permit such operations. The recommended setting is /FULL_DUPLEX. .SKIP 2 11.1.6##ESCAPE Setting a terminal /ESCAPE enables escape sequence processing. Normally, an escape character in the input stream is treated as a terminator, but if escape sequence processing is enabled any characters which follow the escape are examined. If the characters form a proper escape sequence then the entire sequence is passed as the input stream terminator. Some commercial language runtime systems assert this attribute regardless of the setting. The recommended setting is /ESCAPE. .SKIP 2 11.1.7##EIGHTBIT This attribute determines whether seven or eight bit bytes are exchanged between the terminal and the operating system. If your application makes use of Digital's Multinational Character Set you should set the terminal /EIGHTBIT. You may also wish to use this attribute if you have a modem attached to a particular terminal line. Many of the asynchronous file transfer protocol's require eightbit support. In this case you must set the terminal characteristics in the system startup command file. .SKIP 2 11.1.8##HOSTSYNCH The hostsynch attribute is used with block mode terminals or with any device which may send a long string of characters to the operating system. If hostsynch is enabled and if the typeahead buffer is in danger of overflowing, the terminal driver sends an XOFF character to the terminal. When the characters have been processed and there is more room in the buffer, the driver sends an XON character. This attribute causes extra processing in the terminal driver and should only be used when necessary. The recommended setting for interactive terminals is /NOHOSTSYNCH. .SKIP 2 11.1.9##SERIAL Normally RSX permits parallel command execution. If a first command typed at a terminal is followed by a second before the first has completed, the two execute in parallel. Setting the terminal /SERIAL causes execution of the second command to be postponed until the first is complete. The recommended setting is /SERIAL. .SKIP 2 11.1.10##SLAVE A terminal which has the /SLAVE attribute does not accept any input unless it has been attached by an application program. This attribute is useful in situations where very inexperienced operators are using the system. If such a user is running at an unslaved terminal and the application aborts, the user is confronted with the CLI and might do some inadvertent damage. If the terminal is set /SLAVE, input characters are only accepted while the application is alive and well. If the program aborts, the terminal ignores any further input until it is set /NOSLAVE from another terminal, or the system is restarted. Note that the /SLAVE attribute should be set as part of the login process and /NOSLAVE set as part of logout. A-to-Z automatically sets terminals /SLAVE for all the user accounts. .SKIP 2 11.1.11##LOWERCASE Terminals set /LOWERCASE echo characters just as they are typed in. If the terminal is not set /LOWERCASE, characters are converted to their uppercase equivalent before they are echoed. /LOWERCASE is the recommended setting. .SKIP 2 11.1.12##WRAP Terminals which are set /WRAP automatically wrap lines which are longer than the line width setting. The terminal driver is not quite smart enough to keep track of cursor positioning, however, and if the terminal is set /WRAP, application screens may be corrupted by the automatic wrapping. /NOWRAP is the recommended setting. .SKIP 2 11.1.13##TYPEAHEAD Setting a terminal /TYPEAHEAD directs the operating system to collect characters which are typed as input and to save them for a subsequent read request by an application. If the terminal is set /NOTYPEAHEAD, the characters are discarded or are passed to the default CLI. /TYPEAHEAD is the recommended setting. On M-Plus systems the command may be used to set the size of the typeahead buffer as in SET TERMINAL/TYPEAHEAD:nn. If you are using a block mode terminal or have other special requirements you may wish to change the typeahead buffer setting from its default size of 86. This option is not available on Micro/RSX. .SKIP 2 11.2##Partitioning Memory The earliest versions of RSX required that the developer determine the amount of memory available and divide it up into fixed partitions. With the introduction of the system controlled partition (GEN) this is no longer necessary and most commercial applications require nothing more. There are, however, three, comparatively simple, allocation decisions remaining. Memory usage may be divided into four general classes - three of which the developer can allocate - and the developer should assure that the memory allocated to each class is sufficient to the task. The four classes are the Executive, secondary POOL, task space and the disk cache region. You may have to add memory to your system to attain acceptable performance. .SKIP 2 11.2.1##Exec and Primary POOL The RSX Executive and its dynamic memory region, primary POOL, are fixed in a special region during the system generation process. The size of this region is fixed and POOL space is set to the highest possible value. There is little that you can do to change this allocation. .SKIP 2 11.2.2##Secondary POOL and Extension Secondary POOL is another region of dynamic memory which is used by the Executive for a variety of purposes including task header and logical name storage. The size of secondary POOL is established during system startup. Because secondary POOL is used for so many different purposes it is impossible for RSX to predict a suitable allocation figure with any accuracy. You should take care to examine your application in a production environment and assure that the amount of memory allocated to secondary POOL is adequate at peak load. The RMD memory display indicates current utilization and high water mark figures for secondary POOL usage. If secondary POOL runs low or is exhausted, performance suffers and the system may malfunction. Excess POOL allocation is wasted memory. The default size of secondary POOL is set during system generation. You may increase the allocation by extending the POOL. On Micro/RSX and Pregenned M-Plus you extend secondary POOL with the SECONDARY_POOL statement in SYSPARAM.DAT. On M-Plus you must include LOA /EXP=SEC/HIGH/SIZE=nnn in your startup file. The size parameter is the extension quantity expressed in words (not bytes). .SKIP 2 11.2.3##Task Space Task space is the area of memory in which tasks, libraries, common regions and loadable drivers reside. If there are more tasks installed on the system than can fit in this region, some of them are moved to the checkpoint file on disk. Checkpointing active tasks against each other is a common source of performance problems. You can use the RMD Memory display to examine your system memory requirements under load. You need approximately 256KB for RSX plus 64KB for each interactive user plus 64KB for each background processor or batch stream. Tasks which have memory overlays require more memory and must be included in these calculations on a case by case basis. Space for tasks is not allocated but is, rather, what remains after the Executive, secondary POOL and cache allocations have been made. Nevertheless, the amount of memory required for tasks affects the allocations you make for POOL and cache. .SKIP 2 11.2.4##Cache Region When you have allocated sufficient secondary POOL and have determined how much memory you need for tasks, throw the remainder into the cache region. Cache is a means of substituting (comparatively) cheap memory for much more expensive, high performance disks. The bigger the cache is, the better performance you attain. On Micro/RSX and Pregenned M-Plus you set the size of the cache region with the CACHE= statement. On M-Plus you must insert a SET CACHE command in your startup command file. For hints on getting the most from your disk cache area, see the section on caching, later in this chapter. .SKIP 2 11.3##Disks One of the principal determinants of system performance is disk I/O. Because the movement of the disk head and the rotation of the platter are mechanical operations there are inherent delays during which no processing can occur. This condition is further aggravated on small system configurations where the number of spindles is limited and the contention for head positioning is intensified. There are a number of system components which make demands on the disk including system services, task activation and loading, overlays and, of course, reading and writing data files. Understanding each of these areas is important to understanding the overall system throughput - moving the disk head away from a data file to load an overlay segment from a task image incurs not only the delay in loading the overlay but also the delay in returning the head back to its position over the data file. Making the most efficient use of the available disk capacity on a system requires you to have a basic understanding of the disk structure On Disk Structure Level 1 (ODS-1) and the file system (RMS). The principles described here pertain whether or not RMS is used for record management. Furthermore, this is an aspect of application development in which there is a great deal of similarity between RSX and VMS. Any improvements made to the performance of an application on RSX also improve the performance of the application on VMS. .SKIP 2 11.3.1##Initializing Before a disk can be used by RSX for any file structured operation it must be initialized. Initialization is the process of creating an empty ODS-1 directory structure on the disk such that user files can be created and managed. The system disk is usually initialized during installation of RSX. Any additional disks must be initialized manually, an operation which can be performed on-line. .SKIP 2 11.3.1.1##Preparing a Disk Before a disk can be initialized it must be formatted and scanned for bad blocks. All of these operations require that you be logged in as a privileged user and that the disk drive be allocated as a private device. This insures that no other user is granted access to the device. Use the ALLOCATE command and then mount the disk as a foreign file structure with the MOUNT/FOREIGN command. If the disk is a very old type, or if it was not manufactured by DEC, you may need to format it. Formatting is the process of writing sector header and address information on the disk surface. Use the FMT utility. Most modern disks come from the vendor already formatted. Once the disk is formatted it should be scanned for bad blocks. You can direct the BAD utility to write data patterns across the disk and record which blocks on the disk fail to return the information correctly. The location of the bad blocks is written into a special area on the disk. During initialization these blocks are collected together into a special file (BADBLK.SYS). Since they are allocated to this file they are not used by the file processor for storing data. Newer disks, such as the RDxx series, already have the bad blocks information recorded on the disk volume. .SKIP 2 11.3.1.2##Initializing a Volume Use the INITIALIZE command to write the skeleton directory structure to the disk. This operation creates the Master File Directory, allocates file headers and creates a storage bitmap for the disk. It also creates the bad block file and a null checkpoint file. All these files are stored in a special system directory ([0,0]) on the volume. When you initialize a volume you must supply a label by which the disk is identified during subsequent MOUNT operations. You also specify a number of parameters which affect its subsequent operation such as the maximum number of files and file headers, the volume protection which determines who can access the disk as a whole, the default protection and extension size for files created on the volume. The default values for each of these parameters are usually adequate but there are occasional circumstances, possibly a requirement to store a very large number of (small) files, where you may wish to override the defaults with your own values. .SKIP 2 11.3.2##Mounting Before a disk can be used during a session it must be MOUNTed. MOUNT is the procedure by which the disk is made known to the operating system and the parameters regarding its use are determined. The system disk is mounted during system startup but all other disks, be they physically removable or not, must be mounted through commands. In the case of fixed disks which are used in the day to day operation of the system the mount commands are usually edited into the system startup command file. When you mount a removable disk you should supply the volume label which is checked against the label on the disk itself. You may also supply qualifiers with the MOUNT command which determine whether the volume is to be public (available to all users), shareable (available for MOUNTing by other users), or private. Other qualifiers can be used to override the volume protection, the default file protection and extension quantity, and whether the files on the volume are to be cached in memory. Once the disk has been mounted you may create directories with the CREATE/DIRECTORY command, open and close files, read and write data. .SKIP 2 11.3.3##Dismounting If a volume is removable, and you wish to exchange it for another, you should DISMOUNT the disk before removal. Note that you cannot dismount a disk completely if there are any files still open. This can occur with a volume mounted SHAREABLE where more than one program or user has files open. If not all the files are closed and not all users have dismounted the disk the DISMOUNT command only "marks" the volume for dismount. The actual dismount does not occur until the last active user dismounts the disk. Be careful if you are allowing sharing of removable disks. .SKIP 2 11.4##Creating Directories All files are indexed in directories. A directory is a special file which contains identification information for other files. The Master File Directory (MFD) contains a list of User File Directories (UFD) on a disk volume. A UFD contains a list of user data files. All directory files are created and maintained in a special system area ([0,0]). There is one MFD and zero or more UFDs on each disk. A directory contains a series of data records, each containing the name of a file contained within the directory and information about the location of the file header. The MFD contains a list of all the UFDs on the volume. The UFDs contain a list of the data files contained in the user directory. When a file is to be opened the directory is determined, either explicitly or through defaults, and the MFD is searched for the proper UFD entry. The UFD is then located and it, in turn, is searched for the file entry. The data in the entry is then used to locate the file header in the volume index file. Note that because the search through file entries is sequential, the average time to find a file increases with the number of entries. Collecting large numbers of files together into a directory slows down access time considerably. Directory files have all the properties of data files in that they have protection codes, can be copied, renamed and deleted. The protection of the MFD is the volume protection, that is, it determines which users can access the disk as a whole. If a user is denied read access to the MFD then there is no way to get at any of the UFDs and the data files. The protection of a UFD determines which users can read and/or write the data files listed within that directory. Normally, the system area [0,0] is concealed and is not listed (such as in a DIRECTORY command) along with the other directories on the disk. If you specify this area explicitly, however, you can gain access to the MFD and the UFDs as though they were data files which, in a sense, they are. An RSX expert can create various kinds of magical effects and illusions such as listing a file in multiple directories. But unless you consider yourself to be such an expert, you should leave this area and its contents alone. .SKIP 2 11.5##Files A file consists of a header and a collection of extents. The header is located in the volume index file ([0,0]INDEXF.SYS) and contains information identifying the file, such as the file name and type, the version, the owner ID, the creation date and the most recent revision date. The location of the header block for a file is reflected in the File ID which is a unique identifier by which the file may be located and opened without searching through the directory structures. Some RSX components manipulate files by their IDs. The header also contains a number of extent descriptors which describe each of the segments of the disk which belong to the file. Available disk blocks are listed in the disk bitmap file ([0,0]BITMAP.SYS). As a file is extended the header is updated to include the new extents. If the extent descriptors become too numerous to fit in a single header block, an extension header is allocated. This is why the number of headers allocated for a volume (declared during initialization) must always be greater than the maximum number of files. The number and the size of the extents which comprise a file determine the access speed. The extents may be physically adjacent on the disk or they may be quite far apart. If the extents are close together the disk heads spend less time when moving from one to another. When a file is opened, RSX reads the first few extent descriptors into a memory structure called a Window. If a request is made to read or write a logical block of the file which lies outside of the window, RSX must return to the file header (more disk head movement and further delay) to get a new set of extent descriptors (a window turn). The more extents there are in the header, the more often RSX has to disrupt file operations to obtain new window data. RSX normally tries to allocate extents for a file as close together as possible, but the pattern of disk usage may preclude any real optimization. .SKIP 2 11.5.1##File Performance There is a tradeoff between file performance and disk space utilization, that is, it is often possible to improve performance of a file by "wasting" a certain amount of space. There are three actions you can take. First, you can pre-allocate the file as a contiguous space. Making the file contiguous reduces the amount of disk head travel and, equally important, reduces the number of extents required to describe the file. If a file is contiguous there are only a small number of extent descriptors and you may be able to eliminate window turns altogether. The disadvantage is that there may not be sufficient contiguous space on a disk and once the space is allocated to a file it cannot be used for any other purpose. Second, pre-allocating a file improves performance when the file is first written whether or not the file is contiguous. By pre-allocating the extents you eliminate the small extend operations that are otherwise required as the file grows. Third, you can increase the size of the extension quantity or the number of blocks that RSX adds to a file each time it is extended. It is better (though possibly wasteful) to extend the file less frequently and in larger chunks. Even if the file as a whole is not contiguous it is nonetheless helpful if pieces of the file are, since there are fewer extent descriptors and the blocks are clustered. .SKIP 2 11.5.2##File Protection RSX supports the same, multilevel file protection that is used in VMS. Potential users of a file are grouped into four categories: Owner, Group, System, and World. Membership in these groups is determined by UIC. The Owner of a file is a user with the same UIC as that listed as the file owner in the header. A group member is a user with the same group UIC code as the owner. System is the operating system itself and any user with a privileged account (a group number of 10 or less). World is everyone else. For each class of user you may specify four kinds of access. Read access allows the user to read, copy or execute the file. Write access allows the user to modify data within the file. Extend access allows the user to increase the amount of space allocated to the file. (In VMS, there is Execute access rather than Extend access; "execute" is not a concept contained in RSX.) Delete allows the user to delete the file altogether. The protection of a file is determined when the file is created or when it is set or changed with a SET PROTECTION command. A hierarchy of defaults are in effect beginning with the system default and continuing through the volume default and the user default. Only the owner of a file or a privileged user can change the protection of a file. Thus, it is possible for a non-privileged user to set the protection of a file to prevent inadvertent deletion by the system but not to prevent the system or a privileged user from changing the protection to allow subsequent deletion. Note that the protection of a Directory determines which users may access the files identifiers within the directory but not necessarily the file data. You may allow another user access to selected files within a directory or you may lock them out altogether. .SKIP 2 11.6##Logical Names Older versions of RSX supported a very limited logical name facility which could only be used with devices. Beginning with V3.0, however, both Micro/RSX and M-Plus support a VMS compatible logical name facility. Names may be defined in User, Group and System tables, may be nested, and may expand to either partial or full filespecs. Logical names may be established with the DEFINE command or with calls to system services. Since DEFINE does not check the syntax of the equivalence name it is possible to use logical names to convey string information other than file specifications between users and tasks on the system. This facility is used throughout A-to-Z. The logical name translation process follows the same rules on RSX that it does on VMS. When a name is presented to the system for translation the leftmost part is examined. If the leftmost part is terminated with a colon or a space, an attempt is made to translate it and if the translation succeeds, the equivalence name is substituted and the translation is repeated with the new name. When the leftmost portion is terminated with anything except a colon or space the translation process ceases and the resultant name is returned to the caller or used as a file specification. Thus, NAME or NAME:other results in an attempt to translate "NAME" whereas NAME.other or NAME;other does not. Logical names may be defined with embedded colons but the rules for translation become much more complicated and the beginner is advised to avoid this practice. Logical name tables are stored in the secondary POOL. If you plan to make extensive use of logical names you should use the SHOW MEMORY command to see whether the POOL is close to exhaustion and more space should be allocated. .SKIP 2 11.7##Disk Caching Most applications benefit from disk caching. Caching is actually a means by which memory may be treated as a very fast disk. Note that it is always better to eliminate the disk I/O altogether or to eliminate as many sources of I/O as possible, but once this has been accomplished you should enable caching. To make use of caching you must first establish one or more cache regions in memory and then notify the devices which are to use them. You may do both of these with the MOUNT command. More than one device may be associated with a region. When you create the cache region you should specify as much memory as you can afford to spare. Generally, the larger the region is, the more effective the cache is, but this must be balanced against all the other demands made on the system memory. In particular, if you reduce memory available to tasks, you may cause some degree of thrashing which wipes out all the benefits of caching and then some. There is no particular advantage to allocating multiple regions unless you have divided memory into multiple partitions. When you mount a device and associated it with a cache region you may specify the types of operations that are to be cached and the maximum size in disk blocks for each type. Generally the defaults are adequate but you may wish to increase the extent size for VIRTUAL (application data) operations if you use files with bucket sizes larger than five blocks. The extent size should be at least as large as the bucket size or caching does not take place for relative and indexed file operations. If there are a large number of interactive users it might be worth the additional expense of extra memory simply to increase the size of the disk cache. .SKIP 2 11.8##Printers and Queues RSX offers full support for multiple Print and Batch Queues. Queues are named and can be specific to a particular device or generic for a class of devices. Included with this facility is Transparent Spooling of physical devices which permits multiple programs to access a single device simultaneously. There is also support for application specific queues. The Queue manager is also somewhat complex and can be confusing to the neophyte. Names of devices, device processors and queues can be hard to distinguish and the sequence of startup commands on M-Plus is complex. Nonetheless, this is a powerful facility and is one of very great interest to a commercial application developer. For information about submitting jobs, see the Batch and Queue Operations manual. For information about starting and stopping the queues, see the System Management Guide. .SKIP 2 11.8.1##Queue Mechanism A Queue is a collection of jobs waiting for processing. A queue may be specific to a device, or it may be generic and pass a job to whichever device is available. The Queue Manager (QMG) is a task which collects queue requests from PRINT and SUBMIT commands and distributes the jobs to the various queues. A Processor is a task which is assigned to a specific device. Jobs are passed from a queue to a processor for execution. A spooled device is considered to be the device itself along with the associated processor. A Batch processor is not associated with a physical device. .SKIP 2 11.8.2##Submitting Jobs You may submit a job to a queue with either the PRINT or SUBMIT commands. Both commands allow a variety of qualifiers which control the way the job is executed. SUBMIT is used for batch jobs. You may submit a job to the generic batch queue or to a particular queue by name. PRINT is used for print jobs and also for queueing jobs to application processors. You may submit a job to the generic print queue or to a particular queue or device by name. You may also use the PRINT command to direct a job to a particular device or processor by specifying qualifiers such as FORM or LOWERCASE. If you use such a qualifier, the job is directed to a processor initialized with the proper attributes or, if none such exist, it is held until one is created. There are also a variety of commands for controlling jobs already in a queue. You may HOLD a job and then RELEASE it at some later time. You may also DELETE a job after it has been queued. .SKIP 2 11.8.3##Startup Starting up Print and Batch queues on Micro/RSX and Pregenned M-Plus requires only that you edit SYSPARAM.DAT and include the proper QUEUE_MANAGER, BATCH_PROCESSORS and PRINTER statements. Getting everything going on M-Plus is a little more difficult. A prototype QMGSTART.CMD file is provided with the system which starts up one print queue and one batch queue. If this is not sufficient for your needs you must modify the skeleton QMGSTART command file. Making such a change is easier once you understand the general workings of the queueing mechanism. You must install and start QMG. This also initializes the generic PRINT and BATCH queues. Then install the QMG interface QMGPRT. Then, for each device or batch queue you must initialize a queue, install and initialize a processor task and assign the queue to the processor. Each device must have an associated processor which is named after the device. Both print and batch processors are provided with RSX which may be installed with the appropriate task name. Each processor must have an associated queue which has the same name as the processor. You may also initialize generic queues which are assigned to more than one processor. You may also install application processors and initialize the associated queues. Implementing such a processor is a more advanced aspect of application development on RSX and is mentioned here only to indicate that such a capability is available. .SKIP 2 11.8.4##Shutdown If your application or system makes frequent use of queues you should assure that system shutdowns are conducted in an orderly fashion. Information about jobs awaiting execution is maintained in a file (SP0:[1,7]QUEUE.SYS) and if the system is shutdown abruptly while processing is in progress it is possible that output data may be lost. RSX is provided with a system shutdown command file (LB:[1,2]SHUTUP.CMD) which, among other things, assures that system queues are shut down in such a way that they may be restarted properly when the system comes back up. You should assure that your operators use this command procedure or provide the same functionality via an application program. .SKIP 2 11.8.5##Transparent Spooling One of the features of the RSX queue architecture is Transparent Spooling. A device which is spooled may be accessed by more than one program simultaneously. When a program Opens such a device, usually for output, the file system passes the data to the processor instead of directly to the device. The processor, which has the same name as the device, accumulates the data in a temporary file and when the program closes the device channel, the data file is queued, along with all other jobs, for the physical device. You may output a file to a spooled device by COPYing the file to the device name. The COPY command queues the request as though you had used a PRINT command. The advantage of this is that multiple programs may perform output to a device, such as a printer, without assigning the device for exclusive use or even determining if it is in use. The disadvantage of this is that the program cannot determine whether output is going directly to a device or is being accumulated in a file. Programs which generate very large amounts of output may inadvertently fill up the disk. Another problem with transparent spooling is that programs which require specific device control, such as a word processor which wishes to stop printing at the top of a page and await a user command, cannot determine whether it actually owns the device or not. The solution for both of these problems is for the program to suspend the queueing operations temporarily, perform the operations and then restore the queue. You can do this directly from your program by spawning DCL with the following series of commands. This example assumes that the spooled device is a printer. STOP/QUEUE queuename. Following this command, jobs no longer are taken from the queue, although they may still be added to it. STOP/PRINT processor_name/JOB_END. This command directs the processor associated with the printer to stop at the end of the current job. The processor name is usually the same as the printer name, such as LP2. Once the current print job is complete the processor releases the printer. Then, from your program, spawn DCL to ALLOCATE the printer. This command fails while the printer is still busy, but succeeds once it is free. You may then Open the printer and be assured of full, direct control over the device. When your program is finished with the device, you should restore it to spooled status. Spawn DCL with a DEALLOCATE command to release the device. Then spawn the START/PRINT processor_name and START/QUEUE queuename commands to resume normal operations. .PAGE .CENTER Chapter 12 .SKIP .CENTER Troubleshooting .SKIP 2 The performance of a system as a whole is dependent on the amount of resources required by an application and the efficiency with which the available resources are managed. The tuning process must begin by reducing the resources required by an application to the absolute minimum. It is always better to eliminate the need for a resource than it is to improve its availability or performance. Once the application tuning is complete, you may begin determining that the resources available on the system are adequate to the demand and that they are being managed properly. There is little that a well tuned system can do to improve the performance of an application which is inefficient or is consuming an inordinate number of resources. On the other hand, there are some ways that a poorly tuned system can slow things down. If the system is not managing available resources well, then performance suffers. The tuning process is one of identifying resources which are insufficient or which are being managed poorly. .SKIP 2 12.1##Before You Start A common cause of system performance problems is insufficient hardware. There may not be enough memory. The processor or disks may be too slow. Another possibility is that error rates on malfunctioning devices may be impeding the application by causing excessive numbers of retries. This is not to say that you should blame all your problems on hardware but rather that you should not overlook the obvious. Once you are satisfied that the hardware is sufficient to the task and is working properly, you should begin examining the way in which it is being used. .SKIP 2 12.2##Diagnostic Tools There are three tools provided with RSX which can be used to examine a system under load and which may point out which resources are in short supply or where imbalances have occurred. The use of these tools is not something that you want to leave to an inexperienced user, however, and may require that you be on site. .SKIP 2 12.2.1##Resource Monitor Display (RMD) RMD is the single most useful tool for diagnosing system problems and observing system operation in general. It is invoked from DCL with the SHOW MEMORY command and has a variety of displays which provide information about the behavior of the system and the usage of various resources. If you are having a performance problem, begin your diagnosis with RMD. RMD has a number of different screens which present various sets of information about the system. You can switch from one screen to another as well as changing the rate at which the screens are updated with new information. You can even invoke RMD over a dial-up line to investigate problems at a remote site. The Memory display is the first to appear and you may switch from one display to another on the fly. See the chapter on RMD in the System Management Guide for more information. .SKIP 2 12.2.1.1##Memory The Memory display is the most frequently used and contains a great deal of information. The display portrays system memory and shows all the tasks and regions in their approximate locations. You can watch programs move in and out as terminals proceed through an application. The display also shows the current and "high water" usage statistics for primary and secondary POOL, the amount of free space on each of up to four disks, the name of the task currently executing, and a summary of how many tasks are in memory versus how many are checkpointed to the disk. The display also shows the latest sequence number being used by the Error Logger. If you have enabled Error Logging on your system and you see the sequence number changing frequently it may indicate that your hardware is marginal. .SKIP 2 12.2.1.2##Active Task Display The Active Task display is simply a list of all the tasks which are active on the system. Each task is listed by name along with size, priority, and status information. This is, perhaps, less useful to a commercial programmer than the others. .SKIP 2 12.2.1.3##Task Display The Task display shows the contents of the header for a particular task on the system. The header is a region of memory that RSX uses to maintain task context and contains various information such as hardware register contents, priority and status indicators. You can use the task display to examine the operation of any program on the system in some detail. You can watch the program open and close files, enter and leave certain processing states and change size. In particular, if you observe the list of files in use by the program to be changing rapidly you may have a problem with too frequent file opens. .SKIP 2 12.2.1.4##I/O Counts Display The I/O Counts display shows the I/O and error logging counts for up to six mass storage devices. You can use this display to examine the distribution and level of disk activity on your system. You can also check for errors accumulating on a device. If you notice that a particular device is showing a disproportionate amount of activity you may need to redistribute the load by moving programs or files from one device to another. You should also study the individual activity level for each drive. If a particular RD series disk is showing anything over 20 I/O requests per second, the device may be saturated. .SKIP 2 12.2.1.5##System Statistics The System Statistics display shows you a variety of general information about the operation of your system. The information ranges from the total number of user logins to the average number of QIOs issued per second. You can obtain information about CPU utilization percentage of memory and checkpoint space being used, and the rate at which tasks are being checkpointed. You should pay particular attention to memory utilization and checkpoint frequency. It is acceptable and appropriate for an inactive or suspended task to be checkpointed to disk, such as a menu driver which is waiting for a selected application to complete. This frees up system memory for tasks engaged in active processing. However, if the display shows that tasks are being checkpointed on a more than occasional basis, it may be that active tasks are being checkpointed against each other. This condition, called thrashing, is the worst performance problem you can have on RSX and must be corrected by decreasing the number of active tasks (users) or increasing the amount of memory. .SKIP 2 12.2.1.6##Cache Region Display The Cache display shows general information about the disk caching on your system. By comparing the total number of reads and writes to the number of cache hits you can determine the effectiveness of the cache. If the hit rate is below 50%, then you are not getting maximum benefit from cache and you should adjust the cache parameters for better performance. You should also note the Cache Used statistics. If the percentage of a region in use is very high or very low you should adjust the size of the region accordingly. .SKIP 2 12.2.1.7##Detailed Cache Statistics The Detailed Cache statistics display shows the finer details of usage of a particular cache region. This display contains more information than is usually required by commercial developers, though it may be of use by an expert for very fine system analysis and tuning. .SKIP 2 12.2.2##Error Logging RSX supports an extensive error logging facility which can be used for detecting and recording errors occurring on the devices and memory in your system. The error information is detailed, and is collected for both soft (recoverable) and hard (non-recoverable) errors. The information collected assists service personnel in diagnosing and correcting hardware problems. Intermittent errors may affect performance of the system. If you are experiencing a performance problem you may use error logging to either identify a specific problem or to eliminate hardware errors as the source of your problem. You must explicitly enable error logging by toggling the ERROR_LOGGING statement in SYSPARAM.DAT on Micro/RSX and the Pregenned M-Plus, or by including the appropriate ELI statements in your STARTUP.CMD file for M-Plus. See the Error Logging Manual for further details. The error logging facility consists of four components. The logging task itself, ERRLOG, accumulates error log packets, generated by the Executive when an error occurs, and collects them in a log file, usually LB:[1,6]LOG.ERR. The user interface (ELI) sends command packets to ERRLOG and is used to start, stop and control logging activity. The reporting facility (RPT) is used to analyze the information in the log file and format it for use. The fourth component (CFL) is used for modifying the logging facility, such as when a foreign device is added to the system. Its use is not normally required. You may use error logging for detailed diagnosis or, more simply, as an early warning mechanism. Activity in the ERRSEQ field in the RMD Memory display indicates that errors are occurring. Note that this field is not updated unless logging is explicitly enabled as described above. Note also that if you have enabled logging, and errors are occurring, there may be considerable growth in the log file. Check the size of this file from time to time to assure that it isn't gobbling up your disk. .SKIP 2 12.2.3##Resource Accounting Resource Accounting provides a record of system usage. Data is gathered for individual users and for the system as a whole. You can use this accounting as part of your customer billing operation but you can also use it to evaluate the operation of your system. You can direct Resource Accounting to collect information about disk activity and throughput, about the usage patterns of individual users of your system or about particular tasks on the system which are suspected of heavy resource usage. Resource Accounting is automatically enabled on Micro/RSX and Pregenned M-Plus. On M-Plus you must include the appropriate START/ACCOUNTING statements in your STARTUP.CMD. See the Resource Accounting chapter in the RSX System Management Guide for further details. Accounting works much like Error Logging, that is, packets of information are generated by the Executive and are collected in a file by the accounting facility. You can enable and disable accounting with DCL commands in order to collect information only during times of special interest to you. Once some data has been collected you may use the SHOW ACCOUNTING command to examine and format the information. You may specify that only statistics for a particular terminal or task be reported. Normally, Resource Accounting only collects information about the system as a whole. You may optionally direct that statistics be collected on each task. This may be useful in Before/After comparisons of application modules. To enable task accounting you must add the TASK:YES parameter to the START/ACCOUNTING statement. If you are using accounting you should take care that the accounting file does not use too much space on your disk. When accounting statistics for everything on the system are gathered, the data can pile up pretty quickly. This is particularly true if you are collecting task statistics. The default accounting file is LB:[1,6]ACNTRN.SYS. .SKIP 2 12.3##What to Look For There are a number of symptoms you should be looking for if you suspect that your system is performing below its capability. Many of these conditions can be detected by using RMD and interpreting the data in light of your knowledge of the architecture of the application. Once you have identified a problem area you must take some corrective measure. Generally the nature of the symptom suggests one or more actions to take. .SKIP 2 12.3.1##Disk Saturation Probably the most common problem encountered on a small system is saturation of the disks. Configurations are limited by price sensitivity to small numbers of drives and the disk head becomes a potential bottleneck. Use the RMD I/O display to examine the QIO rate for each disk. If you see that the rate is close to the maximum as determined by average access times for the drive, then you have identified a bottleneck. More than 20 operations per second for a particular RD series disk drive usually indicates saturation. .SKIP 2 12.3.2##Insufficient Memory Use the System Statistics display of RMD to determine the percentage utilization of memory. Memory on the system is specifically allocated for the system Executive and the various common, secondary POOL and cache regions. Whatever memory remains is available for tasks. If the percentage utilization of memory is very high, there is the possibility that there are more active tasks than can fit. In this case, the Executive begins freeing up memory by moving otherwise runnable tasks to the checkpoint file. This condition is called thrashing and is a cause of extreme performance degradation. Consider the different demands being made on system memory. There is little you can do about the size of the Executive and the common regions such as RMS and the language processors. Secondary POOL usage varies from time to time, but a maximum usage can be established over time and any memory allocated beyond the maximum is wasted. Tasks which have been suspended until some external process occurs may be safely checkpointed, and require no memory until they become active once again. Most applications are designed with one interactive task for each interactive user with perhaps a small number of background or batch processes running concurrently. PDP-11 architecture generally limits the memory requirements of disk overlaid tasks to 64KB for each user or process. Memory overlaid tasks must be evaluated individually. It is usually sufficient, therefore, to allocate about 64 Kb for each interactive user and for each background process. All remaining memory may be allocated to the disk cache region. .SKIP 2 12.3.3##Unbalanced Load While you are in the I/O display of RMD notice whether disk related QIOs are evenly distributed across all the drives. If one drive shows much greater activity than others, investigate the cause. There are many system operations which require disk I/O and some of them, such as program overlays or implicit spooling, may have escaped notice. You may be able to even out the load by simply moving commonly used programs or libraries from one disk to another. .SKIP 2 12.3.4##Insufficient POOL Use the Memory display of RMD to assure that there is sufficient free space in both the primary and secondary POOLs. Primary POOL space is fixed during SYSgen and is generally sufficient. Secondary POOL, however, is used for a wide variety of purposes and may be running low. Note that the percentage figures calculated for secondary POOL may not be correct if the POOL has been extended. If you suspect that POOL may be running short, increase the allocation. .SKIP 2 12.3.5##File Contention File or record contention is sometimes difficult to detect and requires knowledge of the underlying application. Excessive contention can occur if the application has been converted from CTS-300 or VMS without regard to the differences in the way RMS treats access combinations on shared files. .SKIP 2 12.3.6##Low Cache Hit Rates Use the RMD Cache display to assure that cache regions are showing high hit rates and are being used to about 80% of capacity. Cache regions should be allocated with good measure, but not to the extent of reducing memory available to other system facilities. If hit rates are low, find out why and take whatever corrective actions are necessary. It may be that you have forgotten to enable caching for certain disks or have chosen the wrong combination of operation types. The size of the region may be too small to be effective. If the percent usage of a region is high but the hit rate is low, try increasing the size of the region. It may also be that the default extent size for a particular I/O operation type is too small. I/O requests larger than the extent size are never cached. This condition is reported on the Detailed Cache Statistics display of RMD. If any high activity files have bucket sizes greater than five blocks, increase the extent size for VIRTUAL operations to equal that of your bucket sizes. It may also prove that program overlays show a high Extent Too Big rate requiring an increase in the extent size for OVERLAY operations. .SKIP 2 12.3.7##Insufficient Checkpoint Space Use the RMD System Statistics display to assure that there is always space available in the system checkpoint files. If no free checkpoint space can be found, the system locks up until enough tasks exit to free up the required space. .SKIP 2 12.3.8##Excessive File Opens Use the RMD Task display to examine the major components of your application while the system is under load. The display shows which files are open, and you may discover that the list of files changes frequently. This means that files are being opened and closed, and if these operations are occurring often it slows down other disk processing. .SKIP 2 12.3.9##Overloaded Directories Use the DIRECTORY command to look at the distribution of files across your directories and disks. The more files there are in a particular directory, the more "expensive" file opens become. If you have one directory with a large number of files, consider separating the files into multiple directories. Better yet, add a disk drive to the system and redistribute users and files accordingly. .SKIP 2 12.3.10##Jobs at Wrong Priority Check to see that all tasks on the system are running at the correct priority. If you have inadvertently set the priority of a non-critical task higher than that of more important programs, performance suffers. Responsiveness of terminal interactive tasks may be increased by increasing their priority somewhat. .SKIP 2 12.3.11##Misuse of Batch Scheduling of batch processing on RSX is extremely flexible. Considerable performance gains may be achieved by scheduling non-critical batch processing for off hours. You may also be able to improve performance by using multiple batch queues. Use the SHOW QUEUE command to examine the condition of the queues on your system.