U. S. Geological Survey Fall '82 Submissions Installation and Release Notes I. Introduction This document describes the program submissions on the kit and the installation process. System managers and programmers responsible for installing the kit may find this document useful. For detailed information on the code or command files themselves, please consult the particular component. The commenting of the source files is complete (we think). Feel free to write us at the address below if you have a question which these notes and the code fail to answer. II. Installation process The entire installation process is driven by the USGSF82.CMD command file. The purpose of the command file is to determine the location of necessary files (RSXMC.MAC, RSX11M.STB, etc.), and then pass this information on to each program's command file, located in the Universal Library USGSF82.ULB. The $BATCH mode of the command file was installed so that the kit could be easily regenerated when you perform a new SYSGEN. Unless you change operating systems, the object modules created during the initial kit build can be used to generate the task images. The command files always look for the object files; if they aren't there, the assembly step is repeated. USGSF82.CMD returns the following exit status to the parent command file: "Success" (1) If no problems were detected during kit build "Warning" (0) If one or more of the kit modules failed to build successfully "Error" (2) If a fatal error was detected in USGSF82.CMD (this is unlikely) The contents of the Universal Library USGSF82.ULB is as follows: Component Modules Description --------- ------- ----------- CSH CSHCMD Command file CSH Source file CWD CWDCMD Command file CWD Source file CWDCSI Source file VLFREE Source file DVCDAT DVCCMD Command file DVCDAT Source file Component Modules Description --------- ------- ----------- SNAP SNPCMD Command file SNAP Source file WHO WHOCMD Command file WHO Source file WHOCSI Source file WHODAT Source file WHOFND Source file WHOLOG Source file WHOOUT Source file MCR ACT11M ACTFIL module from MCR.OLB ACTMPL ACTFIL module from MCR.OLB FNDUCB $FDUCB module from MCR.OLB USERMAC USERMAC Terminal output macro file III. CSH (Checkpoint Space Handler) Implementation and Notes Command syntax: >CSH [ddn:] [/switch] Legal switches: /LI The listing switches list the contents of checkpoint /FU files for a particular disk or for all disks. /FREE Causes an 'ACS ddn:/BLKS=0' to be spawned with guaranteed inactivation of the checkpoint file. (privileged users only) /HE Prints the help message. Default switch: /LI Briefly, dynamic checkpoint files are handled like memory partitions. Each checkpoint file has a main PCB (Partition Control Block), which is linked with other file PCB's in the system. Checkpointed tasks are treated as subpartitions within the checkpoint file partition. CSH simply scans the chain of PCB's, collecting the size of each file and the map of the partition. This map is then output for /LI and /FU operations. The /FREE operation is trickier. If the file is still active, CSH spawns ACS to deactivate the file; with any luck, the file goes away at this point, and CSH simply exits. If the file hangs around, then there will be two "flavors" of checkpointed tasks in the file: tasks which are actively competing for memory (including tasks in "waitfor" states), and tasks which are stopped or blocked by a CLI command. The latter class of tasks is the troublesome case for CSH. As long as a task is stopped, unless an AST is delivered, the loader will NEVER reload the task into memory. The bits that the $NXTSK routine examines are TS.STP (task stopped by CLI) and T2.STP (task stopped) in the TCB status words. CSH only deals with checkpointed tasks which are stopped. CSH saves and clears these two bits in the TCB and calls $EXRQN to request the task. The task is placed in the loader queue, and CSH (at priority 240.) waits for the task to be loaded. The saved bits are then restored to the TCB. When the last task on the checkpoint file has been loaded, TKTN deallocates the file PCB and the checkpoint file is finally gone. CSH could use careful scrutiny. I am especially concerned about any "holes" that CSH can fall into with its interaction with the Executive. Features which would be nice to add to CSH are: - a /POSITION:n switch which would allow any checkpoint file to be moved to a different place in the list of the file PCB's. Note that the Executive always checkpoints tasks to the first checkpoint file with a large enough hole to accomodate the task. the /POS switch would allow managers to order the checkpoint files so that faster disks would receive the greatest number of checkpoint requests. - /EXTEND and /SHRINK switches which (whenever possible) would allow the expansion or contraction of a checkpoint file. IV. CWD (Change Working Directory) and PWD (Print Working Directory) Implementation and Notes Command syntax: >CWD [ddn:] [ggg] [,mmm] (All arguments in brackets are optional) Performs the following: 'ddn:' is assigned as device SY0: [ggg,mmm] is set as the default UIC (Any missing arguments remain at their current assignment) >CWD [.:] [.] [,.] Resets any unspecified argument back to its login setting. (A specified argument will leave its current assignment unchanged) >CWD Resets SY0: and UIC to their login assignments. >PWD Prints the current SY0: device and working directory, along with space information on SY0: CWD simply emulates the ASN and SET /UIC commands, with one exception. When a privileged user issues a SET /UIC command, the TI: login UIC is changed along with the current UIC. CWD treats privileged users the same as non-privileged users (only the current UIC is changed). This has an undesirable side effect in V2.0 and V4.0, as explained below. Free space information on the SY0: device is performed without I/O. The disk capacity in blocks is stored in the device's UCB, and the number of free blocks on the device is stored in the VCB (Volume Control Block). Normally, CWD will print a warning if the current SY0: device is not /PUBLIC and is not allocated to the user's terminal. This message may be suppressed at task build time. See CWDBLD.CMD after CWD has been generated, or the CWDCMD module in USGSF82.ULB (where the build file is generated). As mentioned, there is a serious side effect on V2.0 and V4.0 systems with the new Executive CLI support, which only affects privileged users. Currently, when MCR spawns a task for a privileged user, the current UIC and the protection UIC for the task are both set to the terminal's current UIC. The new CLI support does this differently: the protection UIC is set to the logon UIC, and the task's default UIC is set to the current UIC. Although we have no argument with either method of establishing protection UIC's, the fact that MCR does one thing and all other CLI's do another thing is disturbing. V. DVCDAT (Device Database Display Program) Notes Command syntax: >DVC ddn: There really isn't much to add to this, except we have found DVC to be an extremely useful utility for diagnosing problem devices. This is the type of utility which can always be enhanced. Features that I would like to see in the future would be support for UCB extension in secondary pool on M-PLUS systems, support for the new error logging offsets, and on and on. If you have problems with this version of DVCDAT, please write to us. If you have a general wish list item or new feature for DVCDAT, please contact Jim Neeland at Hughes Research in Malibu. After all, this is his baby.... Jim Neeland Hughes Research Labs 3011 Malibu Canyon Road Malibu, California 90265 VI. SNAP (Task Snapshot Utilty) Implementation and Notes Command format: >SNAP [ddnn:=]taskname/SW OR >SNAP /HELP /HE Print help message /[NO]HD Print the dump header /[NO]LU Print information on all assigned luns /[NO]OV Print information about all loaded overlay segments /[NO]ST Print the user stack /ID:N Snapshot identification number /EF:N Event flag for PMD synchronisation /[NO]LI: Print the contents of memory where is up to four pairs of memory blocks specified as low:high (e.g., /LI:20:40:2000:2200) /WR OR /R5 Print memory contents in octal words and RAD50 (default if /LI: is specified) /BY OR /AS Print memory contents in octal bytes and ASCII The defaults are: >SNAP TI:=TTnn/HD/LU/OV/ST/ID:0/NOLI/EF:24 PMD always writes to disk directory [1,4] and automatically spools the output (See the Task Builder Reference Manual, Appendix D) To understand SNAP, you need to understand the SNAP$ macro (Task Builder Reference Manual, Appendix D). SNAP$ is the mechanism which allow any task to generate a snapshot of itself by requesting PMD. The SNAP$ macro is simply a Send Data request followed by a Request Task directive to PMD. The data packet contains all options and arguments required by PMD to process the snapshot. When PMD receives the packet, it stops the target task, produces the dump, and unstops the task. SNAP performs the same operation as SNAP$, except that the send packet is manually constructed in pool, and the target taskname is used as the sender task name in the data packet, so PMD thinks that the target task actually requested the snapshot. A privileged user can SNAP any task on the system (except PMD, of course), so WATCH OUT! A non-privileged user can snap any task that was invoked from the user's terminal. There are some tasks (COT... for example) which appear to be running on a user's terminal which should not be snapped. A table in SNAP.MAC can be modified to exclude such forbidden tasks from being SNAPped. An event flag is required to synchronise PMD with the target task. The default event flag is currently 24 (the highest local event flag not reserved by the system). This can be overridden by the /EF:n switch or by modifying the SNAPBLD.CMD command file. Please be careful not to use a "live" event flag, or you'll ruin your application. VII. WHO (System Activity Utility) Implementation and Notes WHO Commands -- >WHO lists the terminal IDs, user names and UICs of all logged on users, and the names of the active tasks owned by each user. Status codes preceding each task name identify the following task states: Executing (CPU bound) ? Buffered I/O in progress % Stopped & Blocked via CLI command / Swapped out of memory * Active I/O in progress # Waiting for event $ Suspended >WHO last-name -or- >WHO ggg,mmm -or- >WHO [ggg,mmm] causes a search in the system account file for the user's UIC if 'last-name' is specified; otherwise, all user names matching the UIC [ggg,mmm] are matched. The most recent logon date and time are also displayed. >WHO /HE prints a help message on the user's terminal. WHO produces the activity report on the system as follows: - The device tables are scanned for all logged in terminals (including virtual terminals on M-Plus). The UCB addresses and logon UIC's are collected into internal tables. - The system task list is scanned once, matching all active tasks with logged in terminals. The task status bits are copied into internal tables for later analysis. - On M-Plus systems, the UAB's are scanned to retrieve the user name associated with each terminal. If the UAB's aren't around, or the system is RSX-11M, the account file is scanned once, matching account names with the logon UIC's of the logged in terminals. CLI's are explicity excluded from the task scan, and a table in WHOLOG.MAC contains names of other tasks (like COT...) which should be excluded because they appear to be running from the user's terminal. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Finally, here's where you can reach us: Gary L. Maxwell Larry Baker U. S. Geological Survey 345 Middlefield Road MS 77 Menlo Park, CA 94025 (415) 323-8111 x. 2982 If you MUST call us, please call between the hours of 9:00 and 10:00 A.M. Pacific Time. We are happy to help with any problems you may have with this kit.