RSX Cover Document FINALLY The long-awaited (I hope you think it was worth it!) RSX-11M version of the LBL software tools virtual operating system is ready. This note describes the system, and in particular, the new features added during RSX developement. A companion note describes the mass storage requirements, run-time requirements and the installation procedure. The following utilities are available in the RSX system: ar ....... archive file maintainer args ..... concatenate standard input to 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 convrt ... convert pip listing files to LIST carriage control cpress ... compress input files crt ...... copy files to terminal crypt .... crypt and decrypt standard input 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 pattern fc ....... fortran compile and task-build image fel ...... task to destroy process tree and return to shell field .... manipulate fields of data find ..... search a file for a pattern form ..... generate form letter incl ..... expand included files intro .... list on-line documentation kwic ..... make keyword in context index lam ...... laminate files lcnt ..... line count ld ....... task-build image ll ....... print line lengths ls ....... list contents of directory macro .... process macro definitions mail ..... send/receive mail man ...... run off section of users manual mcol ..... multicolumn formatting msg ...... manipulate message files -1- RSX Cover Document msplit ... salvage lost message files mv ....... move (or rename) a file os ....... overstrike - convert backspaces into multiple lines pl ....... print specified lines/pages in a file postmn ... see if user has mail pr ....... paginate files to standard output pwd ...... print working directory rat4 ..... ratfor preprocessor rc ....... ratfor compile - preprocess, compile and task-build resolve .. resolve mail users rev ...... reverse lines rm ....... remove files roff ..... format text sedit .... stream editor sh ....... shell (command line interpreter) shl ...... installed version of shell for easy MCR invocation 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 users wc ....... count lines, words and characters in files wcnt ..... (character) word count xref ..... make a cross reference of symbols Writeups on each of these utilities may be had by executing the man command in the shell. The following comments describe new features not reflected in the man entries: cd: change working directory is supported. See companion document on pathnames for legal input to cd. Note that the synonyms cwd and chdir are not supported. ed: ed can handle files up to 750 lines only, due to the 32 kW task-image limit. Note that ed prompts for input commands, with a switch to change this prompt. fc,ld,rc: are available in RSX-11M. The manual entries are essentially up-to-date. More information on fc and ld may be found farther on in the section entitled "Tools Disk Structure". intro: displays a list of available tools on STDOUT. ls: lists structure-level-1 directories. ls understands the regular expressions of find,change and ed, thus permitting such examples as -2- RSX Cover Document ls %a ......... lists all files starting with the letter a in the current working directory ls tst ......... lists all files with the characters tst anywhere in the file name ls ";1$" ....... lists all files with version number 1 man: is a real utility now, as opposed to being a script file. If no arguments are present, man displays the writeups for all of the utilities (those listed in intro). If arguments are specified, then the writeups for those utilities are displayed. rat4: the string declaration has been added. The rules for its use are: 1. All string declarations in a module must be grouped together. 2. The group of string declarations must appear after all other declaration statements and before any data statements. 3. The format of the string declaration is string name "abcdefghij" name is the name of the character array declared. The value of name may be delimited by single(') or double(") quotes. name may be used anywhere a character variable array can be used. sh: A bare input line of ? directs the user to help in using the system. Command lines starting with # indicate a comment, thus allowing scripts to be commented. BACKGROUND PROCESSES ARE ONLY IMPLEMENTED ON RSX11M. Several commands internal to the shell have been added: home set current directory to home directory xon equivalent to -x switch xoff inverse of xon von equivalent to -v switch voff inverse of von The standard search path for the shell when resolving commands is as follows: 1. current directory 2. home directory 3. usr directory [105,2] 4. bin directory [105,1] In each directory, the routine loccom (the source code is on osprim.w/osprim.r) attempts to find a file with a null extension (shell script files) and a file with a . tsk extension. If a file is found in this search path, its type -3- RSX Cover Document (character or binary) is determined and the appropriate action is taken; otherwise, the command is handed to MCR for execution as is. A command may be explicitly given to MCR through the use of the "x" command as % x help for example. The auto-dropthrough feature may be turned off by specifying the -d switch when invoking the shell. -4- Files and Pathnames The following are legal file specifications to any tool requiring one: file.ext;version [ggg,mmm]file.ext;version ddnn:[ggg,mmm]file.ext;version /ggg,mmm/file.ext;version /ddnn/ggg,mmm/file.ext;version Note that ddnn:file.ext;version is not legal. Valid inputs to cd are the last four above, with the file.ext;version removed. Again note that ddnn: is not valid. None of the utilities assume a default extension, so a filename typed without a period is assumed to have a null extension. The semicolon is a special character to the shell, so it must be escaped with an @ when a file version number is explicitly specified in a command line typed to the shell. When a file is opened at WRITE access, the most recent version of the file is overwritten. In particular, the following command is to be eschewed, since it may garbage up your file: tool file -5- Tools Disk Structure On disk structure of the Tools VOS As currently implemented, the Tools VOS uses six consecutive members of one group on the disk where it resides (ST0:). The system built at LBL uses group 105 - i.e. [105,*], but this is something that can be tailored during installation. Assuming the group used is 105, the current assignment of UIC's is as follows: [105,1] main tools directory; all system task images as well as script files reside here [105,2] site-dependent tools and scripts go here. This directory is part of the normal search path for the shell (current working directory; ST0:[105,1]; ST0:[105,2]) [105,3] scratch files created by the tools go here. [105,4] files formatted by lpr go here (not yet implemented) [105,5] mail directory: the mail data-base is kept here. [105,6] the directory where man entries reside. The bare minimum on [105,1] for a working tools system is *.tsk, dict., intro., mymail., mymail.bld, summary., rlib.olb, spell., msgprim., msgtest., msgprm. and symbols. This set of files occupy ~6100 disk blocks. [105,6] is also essential for the man command. The tools do their own I/O with FCS calls, with the only reliance upon Fortran being the use of the $FCHNL entry point to retrieve the FDB address for a lun. (Note: if you are running F4P v.3.0 with the RMS library, you will have to edit gtfdb.mac before doing the system generation.) The runtime system provides for 6 concurrent open files, using luns 1-6. Lun 7 is a scratch lun used by the runtime system, and lun 8 is always assigned to TI:. Each tool attaches TI:, so that ^O works correctly. The ld tool generates an indirect command file for TKB and spawns TKB to build the resulting task image. Given that the current working directory is dk0:[101,1] and the following ratfor source file called hello.r: subroutine main call remark("Hello world.") return end An rc command line of "rc -c hello.r" will generate hello.obj, and an ld command line of "ld hello" will generate a TKB command file in the following sequence: 1. ld generates the following lines on the file (assuming F4P) dk0:[101,1]hello.tsk;1/fp/cp= dk0:[101,1]hello -6- Tools Disk Structure ST0:[105,1]rlib/lb:.main. ST0:[105,1]rlib/lb 2. ld then appends the file st0:[105,1]tools.tkb to the command file. The version of this file delivered on the tape consists of: / units=8 actfil=6 // If the site supports an FCS resident library, or wishes to link to a modified Fortran library for the tools, the appropriate changes may be made to the tools.tkb file. In particular, the following one is used by the author: / units=8 actfil=6 libr=fcsres:ro // In order to assure correct linkage with the FCSRES, lb:[1,1]fcsres.stb was patched so that word 26(octal) is the characters ESK in rad50 instead of ESL. (FCSRES was built as it comes on the distribution.) One of the tools (ls) needs the ".XQIO" entry point from the resident library, and this patch assures that any globals not in the resident library will be linked in correctly. Structure of the Distribution Tape The distribution tape, unless specifically requested otherwise, is a 9-track, 800 bpi, DOS-format tape created with FLX. Four UIC's are represented: [307,30] command file to install the tools, this document, and a working task image for FFL, the fast filex utility [307,31] the fortran and macro sources for building the system, along with all script files necessary for the system to run. [307,32] the pre-roffed manual entries for use by the man command. [307,33] ratfor source code for the system, as well as roff input files for various documentation on the tools. -7- Run-time Requirements of Tools VOS One global logical device name must exist - ST0:. As one might expect, this merely points to the disk where the tools directories reside. For ease of use, it is suggested that the task sh.tsk on the tools directory be installed with the name "...SHL". The task fel.tsk on the tools directory must be installed with the taskname "...FEL". FEL allows the user to kill all subtasks created by the shell invoked from MCR. The way to do this is: 1. Type ^C and wait for the MCR> prompt. 2. Type FEL 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 get the termination messages onto your screen. You should see a shell prompt (%) when all is done. If you do not wish to see an extra MCR prompt (>), then terminate the FEL line with an ESCAPE. (The name fel[l] is to depict the felling of the process tree hanging from the login shell.) Fell acts by sending a message to the task named $Tnn.1, which is the name given to the login shell's child. This task propagates the chain of messages, and each task in the tree will die, printing a message on the user's terminal. 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 file as its standard input), the checkpoint file[s] is heavily used. In particular, it must be quite large. A reasonably safe assumption is 500 blocks per simultaneously active tools user. I realize that this may be a hardship for some installations, but little can be done to alleviate the problem. (Moral: one pays for portable code and functionality!) -8- Installation Guide The installation command file ([307,30]kitbld.cmd) normally uses FLX on the distribution tape. If your system does not have a 9-track tape drive, it will be necessary to copy the necessary UIC's from the tape onto some compatible disk medium (RK05 or larger) at another site. To do so, perform the following steps: 1. Login under a priveleged account 2. Mount your disk pack to copy onto 3. Allocate the drive, initialize pack (if necessary), and mount it 4. Ready distribution tape on tape unit (following assumes MM0:) 5. Set /uic=[?,?] for copying FFL (fast filex) 6. FLX /RS/BL:35.=MM0:[307,30]FFL.TSK/DO 7. INS FFL 8. If the target disk(DDn:) is larger than an RK05 8a. FFL DDn:/UF/FO=MM0:[307,*]*.* 9. If the target disk(DKn:) is an RK05 9a. FFL DKn:/UF/FO=MM0:[307,30]*.*,[307,31]*.*,[307,32]*.* 9b. PIP DKn:[307,*]*.*;*/TR 9c. FFL DKn:/UF/FO=MM0:[307,33]*.* -9- Installation Procedure 1. Login under a priveleged account 2. Ready tape or disk with the distribution on it 3. Select UIC to copy kitbld.cmd to 4. if (distribution on disk) PIP *.*=DISK:[307,30]KITBLD.CMD else FLX /RS=TAPE:[307,30]KITBLD.CMD/DO 5. Make sure target volume is initialized and mounted 6. @KITBLD 7. Answer all questions 8. Peruse the ST0:[GRP,MEM]TOOLS.CMD file which has been displayed on the console. This is the suggested tools-specific startup file. The following comments are in order: a. The GBL logical name assignment is essential b. Installation of shl is suggested c. Installation of fel is essential d. Running of shl -c "addr | sort >st0:[105,1]address" assures that the mail database is current with ACNT's database. 9. If you are satisfied with the tools.cmd file as is, or after removing offending, non-essential parts, the following four steps are necessary: a. >SET /UIC=[1,2] b. >PIP *.*=ST0:[GRP,MEM]TOOLS.CMD c. >@TOOLS d. >using your favorite editor, place the following line somewhere in [1,2]startup.cmd before the terminals are enabled for users to use: @LB0:[1,2]TOOLS 10. Now you are finished -10- What is KITBLD doing? 1. Determines a. Target device and unit (LB0 is suggested, if there is room) b. Tools group number (default is 105) c. Member number for tools binary directory (default is 1) d. If building from tape or disk, and input device and unit e. If F4P will be used f. If the OTS for the compiler is in LB:[1,1]SYSLIB.OLB g. If not, file specification for the OTS library - eg. LB0:[1,1]FOROTS.OLB h. If not using F4P, should the tasks be built /FP i. If the tasks should be linked with an FCS resident library (see comments on page 6). j. If so, the name of the resident library (FCSRES). k. Should fortran and macro files be deleted after use (saves ~1100 blocks on target disk) l. Should object files be deleted after use (saves ~1600 blocks on target disk) 2. Copies the necessary files from the distribution 3. Assures contiguousness of . tsk files from the distribution 4. If the binary directory is not [105,1], uses chs and rt4 to modify the site-dependent primitive functions in sitepr.r. 5. Uses lss and chs to generate an indirect command file for the assembler to assemble all of the . mac files. 6. Fortran compiles the primitive functions written in ratfor 7. Creates the ratfor library, RLIB.OLB 8. Builds all of the tasks 9. Builds the manual directory from the distribution medium 10. Builds the mail database 11. Creates each account's mymail. file with the correct protection. 12. Displays the site's tools.cmd file On a non-loaded system, the system generation takes approximately 90 minutes. -11- Source File Structure (How to rebuild the damn thing if I don't like it!) The source code for each tool is contained on the tape under [307,33]tool.w. This file is all the environment necessary to rebuild the tool, provided that the tools VOS is running, of course. The tool.w file (except for ed, msg, rat4 and sh - see below) is an archive containing: 1. All files included in the rat4 source file 2. The rat4 source file, tool.r Suppose that you wish to change the subroutine "module" in "tool". The suggested scenario is as follows: >shl % flx /rs=mm0:[307,33]tool.w/do % 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 version of tool. Repeat the last three steps until satisfied % ar uv tool.w % pip [105,2]tool.tsk=tool.tsk % cat tool.w >/105,2/tool.w Placing the tool in [105,2] means that the shell will now find your version of the tool in [105,2], the site-dependent tool directory. It is a good idea to keep the modified source in [105,2] also, since you may need it to track down a bug found by your local bugfinder person. Rat4, msg, sh and ed are a little trickier, since the source code is so large as to cause the archiver to overflow if the previous tool.w structure is attempted. For these tools, the ".w" archive contains: 1. toolcbl - an archive of the included files 2. each individual source module for tool In the main tools directory [105,1], a file bigbld is available to automatically build the tool from this type of archive. Suppose you wish to modify the shell. Then % flx /rs=mm0:[307,33]sh.w/do % ar xv sh.w module % ed module % ar uv sh.w module % bigbld sh % pip [105,2]sh.tsk=sh.tsk -12- Source File Structure % cat sh.w >/105,2/sh.w Source Differences for FOR vs. F4P The source code for the system is identical for both compilers with two exceptions - fc and ld. The fc utility, which spawns the compiler as a subtask, comes in two flavors on the source uic [307,33]: fcfor.w and fcf4p.w FCF4P generates the following command line for F4P F4P A,A=A.F/NOTR All of the tools primitives and utility source code will be compiled with the NOTR option. If a different default is desired, modify the source code for the routine fortrn in fc.w, after copying fcf4p.w into fc.w. FCFOR generates the following command line for FOR FOR A,A=A.F/NOSN/NOVA/NOLO If this is undesirable, then follow the same procedure as for F4P except copying fcfor.w to fc.w The ld utility, which builds a tool task image, also comes in two varieties on the source uic: ldfp.w and ldnofp.w. LDFP places a /fp switch after the task image name in the TKB indirect command file. LDNOFP places a /-fp switch after the task image name. If you are building a FOR system, but using the FPP or FIS libraries, simply answer the kitbld question "DO YOU WANT THE TASKS BUILT /FP?" in the affirmative when building the system. The task images on [307,31] have been compiled with FOR generating threaded code and linked with the EIS library, since it was felt that these images would then run on all systems building the tools. -13- Adding On-line Documentation A sample scenario for modifying existing on-line documentation follows. The archive /st0/105,1/docu contains the roff input for the manual entry for each tool. If you are preparing new documentation, one of these archive entries can be used as a template. The subsets are given the name of the utility. Suppose you wish to modify the writeup for ar. The steps to take are: % ar xv /105,1/docu ar % ed ar % cat /105,1/pagel >pagel % roff pagel ar % do this until you are satisfied with the writeup % /105,1/ar uv /105,1/docu ar % roff pagel ar >/105,6/ar % rm ar The first invocation of ar is to extract the roff source from the documentation archive. The editor is used to modify the writeup. The file pagel is used merely to set the page length to 62. The modified writeup source is then roffed to see if it is OK. Once it is ok, it is placed back in the archive. The reason that /105,1/ar is explicitly specified, is due to the fact that just typing ar will cause the shell to find the file name ar. in your current working directory, and will try to execute it as a script file. The roffed writeup is then placed in the directory for manual entries, /105,6. The file ar is then removed from the current working directory. -14- 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 the following MCR command >RUN ST0:[105,1]TOOL the tool will prompt for its arguments with an asterisk * before continuing. -15-