.pl 60 .in 0 .rm 70 .he //Release Notes/ .fo //-#-/ .sp 5 .ce 100 VAX/VMS Software Tools VOS Spring 1986 DECUS Distribution David Martin Hughes Aircraft P.O. Box 92426 R1/B206 Los Angeles, CA 90009 .ce 0 .sp 3 This document describes the VMS implementation of the Software Tools Virtual Operating System. For those new to this game, the basic principles behind the software are described in the article "A Virtual Operating System" which appeared in the September 1980 issue of the Communications of the ACM. The contents of this release supercede all previous releases. .sp See the file ``changes.s86'' for a list of changes since the last (s84) release. .ce 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. .bp .ce Currently available tools .sp 2 .in +5 .nf Acat - concatenate nested archive entries on standard output Addr - generate the msg address database Admin - administer TCS file. Alist - generate paginated listing of source archive Ar - archive file maintainer Args - use standard input as arguments for command Asam - generate index for archive file Asplit - salvage garbaged archive files Axref - cross reference symbols in archive files Banner - generate large banner lines BarGraph - draw a 0-100% bargraph of integer data Box - draw boxes around block structure of RatFor or C programs Cat - concatenate and print text files Ccnt - character count Cd - change (current) directory Ch - make changes in text files Chmod - change mode (protection codes) of file Chown - change the ownership of file(s). Cmp - compare two files Comm - print lines common to two files Cron - clock deamon Cp - copy files Cpress - compress input files Crt - copy files to terminal a screen at a time Crypt - crypt and decrypt standard input D - list contents of directory Date - print the date Dc - desk calculator Delta - make an TCS delta Detab - convert tabs to spaces Diff - isolate differences between files E - extended version of "ed" with command editing & history Echo - echo command line arguments Ed - line-oriented text editor Entab - convert spaces to tabs and spaces Esh - extended shell, with intraline editing and history Exist - check for the existence of a file Expand - uncompress input files Fb - search blocks of lines for text patterns Fc - fortran compiler Fd - fast directory list in sort order Field - manipulate fields of data Find - search a file for text patterns Form - produce form letter by prompting user for information Format - format (roff) text Get - get generation from TCS file Grep - search file[s] for a pattern Hsh - shell with history and editing functions Incl - expand included files Intro - list on-line documentation Isam - generate index for pseudo-indexed-sequential access Kill - kill a running process Kwic - make keyword in context index Lam - laminate files Lcnt - line count Ld - loader Ll - print line lengths Lpr - queue file to printer Ls - list contents of directory Macro - process macro definitions Man - run off section of users manual Mcol - multicolumn formatting MkDir - create directories Mv - move (or rename) a file Number - number lines Os - convert backspaces into multiple lines for "printers" Pack - pack words into columns Pl - print specified lines/pages in a file Pr - paginate files to standard output Printf - justify fields of data in fixed-width fields Prlabl - format labels for printing Ps - list process status information Pstat - determine status of process Pwd - print working directory name on standard output Rar - rearrange archive Ratfor - RatFor preprocessor Rc - RatFor compiler Resume - resume a suspended process Rev - reverse lines Rm - remove files Ruler - display ruler on terminal screen Sched - a way to repetitively invoke a command Sedit - stream editor Send - send a message to another user's terminal Sepfor - Split FORTRAN programs into multiple files Sh - shell (command line interpreter) Sleep - cause process to suspend itself for a period of time Sort - sort and/or merge text files Spell - find spelling errors Split - split a file into pieces Suspnd - suspend a running process Tail - print last lines of a file Tee - copy input to standard output and named files Timer - time execution of a process Tr - transliterate characters Tsort - topologically sort symbols Ttt - 3-dimensional tic tac toe Txtrpl - perform generalized text replacement Ul - convert backspaces into multiple lines for "terminals" Uniq - strip adjacent repeated lines from a file Unrot - unrotate lines rotated by kwic Wc - count lines, words, and characters in files Wcnt - (character) word count Whereis - locate file in tree based on partial pathname Who - show who is on the system Xch - extended change utility Xfind - entended find utility Xref - make a cross reference of symbols .sp .ce Formerly released mail utilities .sp Mail - utility for sending mail to local users Msg - utility for manipulating message files Msplit - utility for salvaging message files Postmn - report the presence of mail Resolve - resolve mail system user names Sndmsg - utility for sending mail to other users Users - list valid mail users .fi .in -5 .sp 3 .ce SIG Tape Information on the Distribution .sp 2 These tools are normally distributed on the SIG Tape as a BACKUP container with the name SWTOOLS.BCK The directories in the container file have the following significance: .sp .in +12 .ti -11 [...DISTN] All of the files necessary to build this release of the Tools on VMS. Note that it is now necessary for you to build the images from the source files in this directory. Images and objects are NO LONGER distributed. The system has successfully built on all versions of VMS >= 3.0. .sp .ti -12 [...MSGSYS] The distribution of the Software Tools Distributed Mail System. .sp .ti -12 [...OLDMSG] The TCS archives for the previously released mail utilities. .sp .ti -9 [...SRC] The source for the portable VOS utilities. .sp .ti -9 [...VMS] The source files for the VMS-specific tools and primitive functions. .in -12 .bp .ce On Disk Structure of the Tools VOS .sp 2 The tools system uses 6 directories which may be scattered over one or more of your disks, with an optional seventh directory at the discretion of the site management. Each known directory is defined as a system logical name; each logical name is of the form ddnn:[dir...] - i.e. a device AND directory specification. .sp .in +7 .ti -7 st_bin This defines `~bin', the directory in which the distributed images are built and kept. This directory should have the protection [rwe,rwe,re,re]. .sp .ti -7 st_usr Site-specific tools, scripts and other known files should be kept here (~usr). The protection should be [rwe,rwe,re,re]. .sp .ti -7 st_tmp The scratch files created by the tools are kept here (~tmp). As such, the directory must have the protection [rwe,rwe,rwe,rwe]. In addition, all users of the tools must have a quota on the disk which st_tmp points to, if quotas are enabled on that disk. .sp .ti -7 st_lpr The files formatted by the `lpr' tool which are queued to the print symbiont are kept here (~lpr). The protections and quota considerations are the same as for ~tmp. .sp .ti -7 st_msg The known files for the mail system are kept here (~msg). The protection should be [rwe,rwe,re,re]. .sp .ti -7 st_man The archives and indices used by the `man' and `intro' utilities are kept here (~man). The protection should be [rwe,rwe,re,re]. .sp .ti -7 st_src (Optional) The source files for the tools modified locally should be placed here (~src). .sp .in -7 In addition, the VOS requires two other system logical names to run: .sp .in +2 st_node - the name of your node in a network; if you are not a member of a net, pick one that appeals to you. .sp st_timezone - the three character mnemonic for the timezone in which the machine is situated. Only the first character is used, as routines exist in the library to determine the state of standard/daylight time. .in -2 .bp Two other logical names can be defined at the discretion of site management: .sp .in +2 sys_tools - This should be defined as the same value as st_bin. It is only for compatibility with previous releases. .sp st_new_versions - If this is defined to be the value "YES", then the tools will create a new version of a file when writing a file. This feature has just been added, so there may be some complications with its use. The logical name can be defined in any of the three name tables and have the desired effect. As such, it is an individual option to define it at LBL. .in -2 .bp .ce Runtime requirements .sp The system logical names described above. .sp The file st_bin:tooldef.com defines the tools as foreign symbols so that they can be invoked from DCL. Invocation of the command file from a system login file guarantees the symbol definitions for the tools for all users when they log in. Alternatively, interested users may invoke @@st_bin:tooldef in their individual login.com files. .sp Several of the images need to be installed with enhanced privilege to provide full functionality to all users. They are: .sp .in +2 .ti -2 * ps (GROUP,WORLD) - lists valuable information on processes in the system. .sp .ti -2 * who (GROUP,WORLD) - lists who is logged into the system, and other info. .sp .ti -2 * send (OPER) - inter-terminal write facility that is not specific to any particular type of terminal. .sp .ti -2 * sh (DETACH,CMEXEC) - the DETACH privilege is required by the shell to permit the user to spawn background processes. If this feature is not supported locally, then do not install with the privilege. The CMEXEC privilege permits the shell to redefine the process logical name SYS$DISK at supervisor mode when performing a `cd' command, such that the device assignment remains when leaving the shell. This is done by changing mode to EXEC, redefining the logical name at supervisor mode, and returning to USER mode. .sp .ti -2 * esh (DETACH,CMEXEC) - same as for sh. .sp .ti -2 * hsh (DETACH,CMEXEC) - same as for sh. .sp .in -2 In addition, if `ed' or `e' are heavily used on your system, it is suggested that they be installed /SHARED/OPEN/HEADER_RESIDENT. .sp In the same vein, if the tools have been built with the shared global image, RLIBSHARE.EXE, it should be installed /SHARED/OPEN to facilitate global sharing of the tools runtime library. On V4.x systems, this name should be defined in EXEC mode. If you have problems with the tools or installed images, then try this: (1) Move a copy of RLIBSHARE.EXE from ~bin to the VMS directory SYS$SHARE. (2) Change the install procedure for the tools so that RLIBSHARE is installed from SYS$SHARE rather than ST_BIN:. .sp The file st_bin:tools.ins is a DCL command file which causes the above eight images to be installed with the above privileges, and can be invoked during system startup. The file st_bin:tools.rem may be used to deinstall these images during update. For V3.x and earlier systems, these files are named toolsv3.ins and toolsv3.rem respectively. .bp While the system is being built during TOOLGEN, the file st_bin:sysuaf.mod is generated, which is a DCL command file to cause authorize to modify all accounts on your system to reflect the suggested quota values to effectively use the tools. The suggested values are: .sp .ce 100 PRCLM 10 BYTLM 30000 FILLM 75 TQELM 40 PGFLQUOTA 16384 .ce 0 .sp These values typically permit a user to have up to 5 processes active on his behalf. The most common problem incurred if the quotas are insufficient is the error message .sp .ce "Cannot spawn process" .sp when attempting to invoke images from one of the shells. It is a good idea to peruse sysuaf.mod and remove accounts from it which do not need to be modified. .bp .ce Source File Structure .sp The source code for `tool' is contained in a file [...SRC]tool.tcs (if the tool is portable across operating systems) or [...VMS]tool.tcs (if it is an VMS-specific tool). This TCS source file contains an edit history of all changes made to the source. The output of the `get' utility operating on a `.tcs' file results in a file (tool.w) which is all of the environment necessary to rebuild the tool, provided that the VOS is operational. The tool.w file is an archive containing: .sp .in +5 .ti -3 1. All of the files "included" by the ratfor source code. .ti -3 2. The ratfor source file, tool.r. .ti -3 3. The format input for the manual entry, tool.fmt. .ti -3 4. And optionally, any extra definition files needed to build alternate versions of the tool (eg. sh => hsh). .sp .in -5 As an example, suppose that you wish to change the subroutine "module" in "tool". The suggested scenario is as follows: .sp .in +3 .nf $ !Fetch the file tool.tcs from the appropriate directory in the container $ !file on tape into st_src $ hsh % get ~src/tool.tcs 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.fmt (modify writeup to reflect changes) % ar uv tool.w tool.r tool.fmt % cp tool.exe ~usr/tool.exe % delta tool.w ~src/tool.tcs (Identify in the comments the reason for the changes, and which modules changed.) % format tool.fmt >tool % ar uv ~man/s1 tool % asam <~man/s1 | sort >~man/i1 .fi .in -3 .sp Placing tool.exe in ~usr causes the shell to find your modified version of "tool" rather than the distributed one. The last two commands above cause the manual entry for `tool' to correctly correspond to the utility itself. .bp .ce Source for Primitive and Library Functions .sp The source archive for the primitive and library functions may be found on [...VMS]rlib.w. This archive consists of several modules: .sp .in +3 .ti -3 1. prim.m - an archive of macro files which are written in assembler and used by one or more tools. These routines are VMS-specific. .sp .ti -3 2. lib.m - assembler versions of portable ratfor routines which are used by one or more tools. .sp .ti -3 3. prim.r - archive of ratfor source routines which are VMS-specific and used by one or more tools. .sp .ti -3 4. lib.r - an archive of ratfor archives of portable library routines. .sp .ti -3 5. other files included by ratfor when processing prim.r. .sp .in -3 To assemble any of the modules in prim.m or lib.m, it is necessary to extract the module(s) and assemble them individually .sp % ar xv prim.m directory.mar; mac/nolist directory .sp To modify one of the routines in prim.r, simply extract it using the archiver, edit it up, update the archive, and recompile via .sp % ar xv prim.r dscbld; ed dscbld; ar uv prim.r dscbld .br % rc -cv prim.r .sp To modify one of the routines in lib.r, it is necessary to perform two extractions and two updates, as in .sp .nf % ar xv lib.r arsubs.r % ar xv arsubs.r aopen % ed aopen % ar uv arsubs.r aopen % rc -cv arsubs.r % ar uv lib.r arsubs.r .fi .sp Of course, after generating new object modules for modified routines, it is necessary to make a system-specific version of st_bin:rlib.olb in st_usr, and to replace the object module in st_usr:rlib.olb. It is also a good idea to avoid replacing the modified modules in the archives until you are sure that they work. Writeups on all primitive routines which are to be visible to programmers may be found using the `man' command on section 2 of the manual. Writeups for library routines are in section 3. .bp .ce Manual entry structure .sp In order to simplify the generation of manual entries for utilities and functions, a set of `format' macros are defined in the file `~bin/manhdr'. For the correct working of the `intro' utility, it is necessary that the first three lines of any site-dependent writeups consist of .sp .nf .cc * .so ~bin/manhdr .hd (
) () one line description of the tool or function *cc . .fi where is replaced by the name of the function or tool,
is the section of the manual this entry is for and is the date the document was created. The .hd macro guarantees that the margins are correct, the header line on the manual pages is consistent with the software tools standard, and that .sp .nf NAME name - one line description of the tool or function .sp .fi appears in the writeup. This particular landmark is used by the intro utility to list the one-liners for the known entries in each section. The best method is to peruse the macros in ~bin/manhdr and to look at some of the writeups supplied with the system. .bp .ce Legal file specifications for the tools .sp The following lists legal VMS file specs for the tools and valid tools pathname equivalents: .sp .nf DEC format Path format ------------------------------- ----------------------------------- file.typ.ver file.typ.ver [dir]file.typ.ver /dir/file.typ.ver [dir.sub...]file.typ.ver /dir/sub/.../file.typ.ver [.sub]file.typ.ver sub/file.typ.ver [-.sub]file.typ.ver \sub/file.typ.ver ddnn:[dir]file.typ.ver /ddnn/dir/file.typ.ver host::ddnn:[dir]file.typ.verp /@host/ddnn/dir/file.typ.ver ? ~name/file.typ.ver ? ~/file.typ.ver .fi .sp In all cases, the pathname equivalent consists of replacing the many and varied VMS delimiters by slashes, which is typically a lower-case character on all terminals and is normally easy to strike using the right pinky. In addition, the backslash (\) is used to go up in the directory tree, equivalent to DEC's [-] construct. The ~name capability is available for the seven known directories of the tools system, ~bin, ~usr, ~tmp, ~lpr, ~msg, ~man and ~src. They permit one to write portable scripts for utilities across different operating systems. Also, ~user, where `user' is the login name of a user on the system maps onto that user's home directory. The ~/ is shorthand for the user's home directory. In utilities which manipulate directories, all of the above formats are valid when the file.typ.ver trailer is removed. .bp .ce Changes for the Spring 1986 Release .sp 2 .ce Modified Utilities .sp .in +2 .ti -2 * `addr' has been modified to reflect V4 changes in the SYSUAF.DAT file. The code has also been conditionalized for V3.x or V4.x with the addition of VMSV3 in ratdef. The correct ratdef is selected during the toolgen process. .sp .ti -2 * `banner' now includes the big character file. .sp .ti -2 * `ps' has been modified to reflect changes made in valid directory names (with multiple ] and [ allowed). The Term field has also been widened for the display of longer terminal device names (such as virtual terminals). .sp .ti -2 * `sh' has been modified many times to remove bugs and add features. Refer to changes.86 for more specific information. .sp .ti -2 * `who' has been modified to reflect changes made in valid directory names (with multiple ] and [ allowed). The Term field has also been widened for the diplay of longer terminal device names (such as virtual terminals). .sp .in -2 .bp .ce 100 Changes for the Spring 1986 Release .sp 2 New Utilities .ce 0 .sp .in +2 .ti -2 .sp * `cron' executes commands at specified dates and times according to the instructions in the file ~usr/crontab. Since CRON never exits, it should only be executed once, usually when the system is booted.