Release Notes RSX-11M[+] Software Tools VOS Spring 1981 DECUS Distribution Joseph Sventek Computer Science & Mathematics Department Lawrence Berkeley Laboratory Berkeley, CA 94720 This document describes those changes in the RSX implementation of the Software Tools Virtual Operating System since the Fall 1980 distribution. While this document is incremental in nature, the entirety of the source code and documentation is distributed, due to widespread code modification and enhancements. NOTICE This software is provided on an as-is basis. No guarantee of performance or support is stated or implied. Any errors or omissions in the code or documentation are regrettable, but not unusual considering the man-power and mode of distribution. Written notification of bugs WITH fixes are appreciated and will be incorporated into the next release, if possible. IAS Notice No attempt has been made to install this distribution on IAS v.3. Due to the similarity of the I/O in RSX and IAS, most of the new primitive functions should work identically. With the Fall 1980 distribution providing a base, it should be possible to install this release with few hassles. -1- Release Notes Currently available tools alist - generate paginated listing of source archive ar - archive file maintainer args - use standard input as arguments for command asplit - salvage garbaged archive files cat - concatenate and print text files ccnt - character count cd - change working directory ch - make changes in text files cmp - compare two files comm - print lines common to two files cpress - compress input files crt - copy files to terminal crypt - crypt and decrypt standard input d - fast directory lister in sort order date - print the date dc - desk calculator detab - convert tabs to spaces dspc - display all characters in a file echo - echo command line arguments ed - text editor entab - convert spaces to tabs and spaces expand - uncompress input files fb - search blocks of lines for text patterns fc - fortran compiler fell - fell process tree hanging from login shell field - manipulate fields of data find - search a file for a pattern form - generate form letter format - roff's big brother (text formatter) grep - get regular expression and print hsh - shell with history and editing function incl - expand included files intro - list on-line documentation isam - generate index for pseudo-indexed-sequential access kwic - make keyword in context index lam - laminate files lcnt - line count ld - loader ll - print line lengths ls - list contents of directory macro - process macro definitions mail - send mail malfix - fix up old mail files for MSG man - run off section of users manual mcol - multicolumn formatting msg - manipulate message files msplit - salvage garbaged message files mubld - build multi-user task and resident common mv - move (or rename) a file -2- Release Notes objfix - flag read-only psects in fortran object files as such os - overstrike - convert backspaces into multiple lines pack - pack words into columns pl - print specified lines/pages of a file postmn - see if user has mail pr - paginate files to standard output pwd - print working directory rar - rearrange existing archive rat4 - old ratfor preprocessor ratfor - new "standard" ratfor preprocessor rc - ratfor compile resolve - resolve mail users rev - reverse lines rm - remove files roff - format text rsh - shell with file recognition and RAW tty io ruler - display ruler on terminal screen sched - repetitive invocation of a command sedit - stream editor sh - shell (command line interpreter) sndmsg - send mail to other users sort - sort and/or merge text files spell - find spelling errors split - split a file into pieces tail - print last lines of a file tee - copy input to standard output and named files tr - character transliteration tsort - topologically sort symbols uniq - strip adjacent repeated lines from a file unrot - unrotate lines rotated by kwic users - list valid mail system users wc - count lines, words and characters wcnt - (character) word count whereis - search for file matching regular expression xref - generate cross reference listing -3- Release Notes SIG Tape UIC's with relevance to VOS [307,30] Toolgen.cmd, the command file for building the tools system. [307,31] The Fortran and Macro source files for building the system, plus any script files and other known files necessary for the correct operation of the system. [307,32] The pre-formatted manual entries for the `man' utility. [307,33] Ratfor source code for the system, as well as roff input files for various and sundry documents on the tools. [307,34] The files necessary to build the variable-length send/receive driver for RSX-11M. It may be used for argument passing between parent and child processes. -4- Release Notes On Disk Structure of the Tools VOS The tools system uses six (6) consecutive members of one UIC group divided over two logical disks. ST0: is used for the four read-only directories, while ST1: is used for the two writable directories. The system uses group 105 as distributed, but this can be modified during the installation. Assuming that the default UIC's are used, the current assignments are: st0:[105,1] main tools directory, ~bin. All system task images, script files and other known files reside here. st0:[105,2] location of site-dependent images, script files and other known files, ~usr. Any modified tools, or site-dependent utilities desired to be in the shell's search path should be placed here. This directory is searched by the shell before ~bin. st1:[105,3] scratch files created by the tools go here, ~tmp. st1:[105,4] files formatted by the `lpr' tool go here, ~lpr (not implemented). st0:[105,5] mail directory, ~mail. The mail database and msg help file are kept here. st0:[105,6] man directory, ~man. The manual entries for the tools reside here. In order to save space on the disk, one may refrain from building all of the tools. This can be achieved by copying the files in [307,31] to a disk and deleting the files with `.f' extensions which are not wanted. Note: do NOT delete `sh.f' or `mubld.f', as these are needed during toolgen. The tool summary above may be consulted for one-liners on each tool to determine candidates for deletion. The tools perform their own I/O with FCS calls, with the only reliance upon the Fortran OTS being the use of the $FCHNL entry point to retrieve the FDB address for each line. (Note: if you are running F4P v.3.0 with RMS support, the definition for D.FDB in RDATA.MAC may have to be changed before performing a toolgen.) The runtime system provides for 7 concurrent open files, using luns 1-7. Lun 8 is a scratch lun used by the system. Each tool attaches TI: to enable typeahead and ^O. -5- Release Notes FCS resident library It is strongly recommended that an FCS resident library be used, not just for the tools, but for all of your user-level code. This may be the single most important step you can take to reduce checkpointing and disk utilization in your system. A note of caution: no matter how one builds FCSRES, all of the FCS entry points cannot fit into one 8192 byte segment. If code written with references to one of the non-included entry points attempts to link to FCSRES, TKB will be unable to resolve the reference, since it is unable to extend the FCS psect, $$RESL. A way to eliminate this problem is to patch lb:[1,1]fcsres.stb to change the psect name of the routines in FCSRES. The recommended patch, using ZAP in absolute mode, is to patch location 26 (octal), which contains ESL in rad50, to ESK in rad50. Runtime requirements Two global logical device assignments must exist, ST0: and ST1:. For ease of use, it is suggested that one of the shells (sh.tsk, hsh.tsk or rsh.tsk) be installed as "...SHL". The default shell installed in tools.cmd is hsh.tsk. ~bin/felltree must be installed as "...FEL". FELL permits the user to kill all subtasks in the process tree emanating from the shell invoked from MCR. This can be performed as follows: 1. Type ^C and wait for the MCR> prompt. 2. Type FELL and wait for the termination messages from the subtasks. If your terminal is currently operating in half-duplex, and the bottom task in the tree is reading your terminal, you may have to type a carriage return in order to prime the fall of the tree. You should see a shell prompt (%) when all is done. If you do not wish to see an extraneous MCR prompt (>), then terminate the FELL line with an ESCAPE. Due to the large task images of the tools, and the way that shell scripts are performed (a copy of the shell is spawned reading the script file as its input file), the checkpoint file[s] is heavily used. A reasonably safe assumption is 500 blocks per SIMULTANEOUSLY active tools user. The average number of background process trees active must be included in the count of active users. -6- Release Notes Source File Structure The source code for each tool is contained in [307,33]tool.w. This file is all of the environment necessary to rebuild the tool, provided that the VOS is operational. The tool.w file is an archive containing: 1. All of the files "included" by the ratfor source code. 2. The ratfor source file, tool.r. 3. The roff input for the manual entry, tool.rof. 4. And optionally, any extra definition files needed to build alternate versions of the tool (eg. sh => hsh, rsh). As an example, suppose that you wish to change the subroutine "module" in "tool". The suggested scenario is as follows: >shl % cat /307,33/tool.w >tool.w % ar xv tool.w % ar xv tool.r module % ed module (make changes and write file) % ar uv tool.r module % rc -v tool.r % (test out new tool. repeat last three steps until satisfied.) % ed tool.rof (modify writeup to reflect changes) % roff tool.rof >~man/tool % ar uv tool.w % pip st0:[105,2]tool.tsk=tool.tsk % cat tool.w >~usr.tool.w Placing tool.tsk in ~usr causes the shell to find your modified version of "tool" rather than the distributed one. Placing the modified source archive there permits easy bug-fixing. -7- Release Notes Source Differences for F4P vs. FOR The tools are designed to work with either compiler. Three utilities are dependent upon which compiler is used, with the compiler dependency handled through conditional preprocessing of the source code. During TOOLGEN, three symbol definitions are appended to ~bin/symbols to reflect the answers given to questions concerning the compiler. They are: define(FORT_COMP,FOR/F4P) define(COMP_NAME,"FOR"/"F4P"/"OTHER") define(FLOAT_PT,YES/NO) The compiler name, if not "FOR" or "F4P", is whatever string was answered to TOOLGEN question 7A. If the compiler is F4P, FLOAT_PT is defined as YES, otherwise NO, unless the answer to TOOLGEN question 9 was yes. Given these definitions, `fc', `objfix' and `ld' will conditionally pre-process correctly. -8- Release Notes Running tools from MCR Each tool is built to retrieve its arguments from MCR if it was installed with a "...XXX" name. To make "tool" available as "...TOL" from MCR, simply type the following MCR command: >INS ST0:[105,1]TOOL/TASK=...TOL If a tool is invoked by an MCR RUN command as in >RUN ST0:[105,1]TOOL the tool will prompt for its arguments with args? before continuing. -9-