UTILITY ROUTINES ARAP 1 DFX 14 DSCCPY 15 DSCDIR 20 DSCFORMAT 22 FAC 28 FDU 29 FHD 30 FLB 31 FORUTL 43 INDEX 45 INF 48 LIST 54 LUT 56 MASSAGE 57 ORC 58 PAG 61 PLOTSUBS 62 QUX 69 RCV 71 RNP 72 SPELL 74 SPY 79 SRD 82 TASKER 93 TPC 94 TWOPAGE 100 VOL 102 XMT 103 PAGE 1 ARAP ARAP.OLB PAGE 1 CSIFP.MAC -- USE CSI TO PARSE FILE NAME STRINGS WRITTEN DATE 10/22/77 REVI CALL: CALL CSIFP(CIV,IPT,CSIBLK,NER) WHERE: CIV IS INPUT STRING TO PARSE IT IS TERMINATED BY A BLANK,TAB,OR NULL IPT SUBSCRIPT INTO CIV UPPED TO STRING END CSIBLK STANDARD CSI CONTROL BLOCK NER 0 => OK 1 => ERROR DURING SYNTAX PARSE 2 => ERROR DURING SEMANTIC PARSE 3 => STRING > 33 CHARACTERS THIS ROUTINE IS CALLED FROM DBKOF (THE USER INTERFACE). SEE DBKOF.FTN FOR COMMENTS. CALL DBKOF4 (LUN, MODE, NER) LUN = LOGICAL UNIT NUMBER TO OPEN MODE = 0-3 (SEE DBKOF) NER = 0 IF OK, FCS ERROR CODE IF NOT **NOTE** DBKOF4 IS CALLED FROM DBKOF.FTN - DBKOF.FTN FILLS IN THE FILE DESCRIPTOR BLOCKS BY CALLING FPARS. DBKOF4 SHOULD NOT BE CALLED IN ANY OTHER CONTEXT OR RESULTS WILL BE UNKNOWN. PAGE 2 ARAP ARAP.OLB PAGE 2 + DBKRD/WR - DISK BLOCK READ/WRITE REFER ALSO TO DBKRD.FTN AND DBKCF.MAC AND - X1LU.FTN,X1DR.MAC,X1EF.FTN FOR RECORD ORIENTED ROUTINES. CALL DBKWR (LUN, NR, IBUF, NWR) CALL DBKRD (LUN, NR, IBUF, NWR, NWA) LUN = I*2 LOGICAL UNIT NUMBER OF FILE TO R/W NR = I*2 VIRTUAL BLOCK NUMBER IN FILE TO BEGIN TRANSFER NOTE THAT NR IS UPDATED ON EXIT FROM DBKRD/WR ON EXIT FROM DBKRD NR = NR + (NWR-1)/256 + 1 WHERE 256 IS THE NUMBER OF I*2 WORDS PER DISK BLOCK. IBUF = INPUT/OUTPUT AREA, CAN BE INTEGER OR REAL, BUT NOT BYTE I.E. MUST BE ON EVEN BYTE BOUNDARY. NWR = I*2 NUMBER OF I*2 WORDS TO READ/WRITE, BEGINNING AT NR ABOVE. 1 DISK BLOCK = 256 I*2 WORDS. NWA = RETURNED ONLY FROM DBKRD. I*2 NUMBER OF I*2 WORDS ACTUALLY READ. THIS IS USEFUL FOR CHECKING END-OF FILE CONDITIONS. IF THE END OF FILE IS REACHED NWA WILL BE LESS THAN NWR OR 0 IF A BLOCK IS REQUESTED THAT IS BEYOND THE END-OF-FILE. **NOTES** THERE ARE NO ERROR RETURNS. IF AN ERROR OCCURS DURING THE OPERATION THE PROGRAM WILL TERMINATE VIA THE TRAP INSTRUCTION - CAUSING F4P TO LOG THE MESSAGE. THE COMPATIBLE CLOSE ROUTINE TO DBKRD/WR IS DBKCF. => CALL DBKCF (LUN) =< DBKRD/WR ARE IN DB2:[350,2]ARAP.OLB ALONG WITH DBKOF (OPEN), DBKCF AND THEIR RELATED SUPPORT ROUTINES. FOR THOSE DOING OVERLAYS, THE FOLLOWING IS WHAT IS NECESSARY TO BE EXTRACTED FROM THE LIBRARY. FOR THE OPEN OVERLAY...... OP1: .FCTR [350,2]ARAP/LB:DBKOF:DBKOF1 - OP2 OP2: .FCTR [350,2]ARAP/LB:CSIFP:FPARS:FPARS1:FPARS2 - OP3 OP3: .FCTR [350,2]ARAP/LB:FFNAM:FFVERN:FPCFS:MONTRY FOR THE ROOT SEGMENT...... DISK1: .FCTR [350,2]ARAP/LB:DBKRD:FPUICT FOR THE CLOSE OVERLAY CLOSE1: .FCTR [350,2]ARAP/LB:DBKCF FOR UNOVERLAYED TASKS.... - PAGE 3 ARAP ARAP.OLB PAGE 3 DELET.MAC -- FORTRAN CALLABLE DELETE AUTHOR: LEN DATE WRITTEN: 16-NOV-78 CALL: CALL DELETE (LUN, NERR) WHERE: LUN = FILE'S LOGICAL UNIT NERR = ERROR CODE 0=OK, NON-0=ERROR FBDMOD.MAC -- MODIFY FDB BEFORE OPEN AUTHOR: A. BARR DATE WRITTEN: 4/25/77 DATE REVISED: 04/29/77 10/30/78 LEN - ADDED FIX AND VAR OPTIONS CALL: CALL FBDMOD(LUN, ['NC'!'CC'] [,'SP'!'NS'] [,'LR',LRECL] 1 ['FI'], ['VA']) WHERE: LUN IS LUN # OF LUN TO MODIFY NC=> NO CARRIAGE CONTROL CC=> CARRIAGE CONTROL SP=> SPANNED BLOCKS NS=> NO SPANNED BLOCKS LR=> MAKE VAL OF NEXT PARM INTO LRECL FOR LUN PARMS OTHER THAN LUN MAY BE IN ANY ORDER FI=> SET FIXED LENGTH RECORD VA=> SET VARIABLE LENGTH RECORD PAGE 4 ARAP ARAP.OLB PAGE 4 *FFNAM.MAC -- FETCH FILE NAME INFORMATION FROM FDB WRITTEN DATE 10/27/77 REVISED DATE CALL: CALL FFNAM(LUN,CIV,NC) WHERE: LUN LUN # OF FILE CIV RETURNED AS DEV:FILE-NAME.FILE-TYPE;VER-NO NC NC IN CIV - FPARS2.MAC -- USE .PARSE TO FILL IN FDB AUTHOR: A. BARR DATE WRITTEN: 12/27/77 DATE REVISED: 6-FEB-78 FOR BETTER UIC HANDLING CALL: CALL FPARS2(LUN,DSD,DFNB,NER) WHERE: PAGE 5 ARAP ARAP.OLB PAGE 5 FPUICT DEFINE STORAGE AREA FOR UIC'S /1 WORD PER UINT GATTR.MAC -- GET FILE ATTRIBUTES AUTHOR: J. LEONARD DATE WRITTEN: 09-AUG-79 CALL: CALL GATTR (LUN, IFRTYP, IFRATT) WHERE: LUN = FILE'S LOGICAL UNIT IFRTYP = RECORD TYPE BYTE BUT RETURNED AS I*2 IFRATT = RECORD ATTRIBUTES (I*2) + CALL GETUSE(IUSER) RETURNS NAME OF USER DOING CALLING VERSION OF GETUSR FROM JACKSON LABS MODIFIED BY LEN 3/9/79 SO TASK DOES NOT HAVE TO PRIVLEDGED. MODIFIED FOR IAS VS3.0. TASK NOW HAS TO BE PRIVLEDGED IN ORDER TO GET .CRJOB. LEN 4/2/79 - PAGE 6 ARAP ARAP.OLB PAGE 6 GSTAT.MAC -- PLUG STATISICS BLOCK ADDRESS AUTHOR: J. LEONARD DATE WRITTEN: 08-MAY-78 CALL: CALL GSTAT (LUN, STBLK) WHERE: LUN = FILE'S LOGICAL UNIT STBLK = I*2 STAT BLOCK, 5 WORDS LONG I = IBLUF (BCHR, BVEC) FIND BCHR IN BVEC, IF ENCOUNTER A ZERO BYTE IN BVEC THEN TERMINATE WITH I = -1, ELSE I = POSITION IN BVEC WHERE MATCH MADE PAGE 7 ARAP ARAP.OLB PAGE 7 ICFGS.MAC -- CHARACTER GET/PUT ROUTINES AUTHOR: S. F. HEFFNER DATE WRITTEN: 5/2/76 DATE REVISED: 12/28/76,7/06/77 FOR ASCII USE ***NOTE--THE FOLLOWING ROUTINES (ICHGS THRU ICSPC) ARE NOT ***REENTRANT AND CAN'T BE, SINCE GNXCH/PNXCH DEPEND UPON ***ICHGS ETC. TO SET UP AND STORE ARGUMENTS ACROSS CALLS. ***ALSO, GNXCH AND PNXCH DON'T PRESERVE REGS! ICHGS--INITIALIZE CHAR GET SCAN GNXCH--GET NEXT CHAR ICFGS--ICHGS W/SPECIFIED MAX LENGTH ICSGC--ICHGS+GNXCH ICHPS--INITIALIZE CHAR PUT SCAN PNXCH--PUT NEXT CHAR ICSPC--ICHPS+PNXCH CALL ICHGS(VEC,IICP,ICP) CALL GNXCH(CHAR) CALL ICFGS(IPE,VEC,IICP,ICP) CALL ICSGC(VEC,IICP,ICP,CHAR) CALL ICHPS(VEC,IICP,ICP) CALL PNXCH(CHAR) CALL ICSPC(VEC,IICP,ICP,CHAR) WHERE: VEC = INTEGER*2 VECTOR IICP = INITIAL CHAR POSITION ICP = CHAR POSITION IPE = MAX NO. OF CHARS CHAR = INTEGER*2 VAR FOR CHAR PAGE 8 ARAP ARAP.OLB PAGE 8 ICMP - LOGICAL COMPARE 09-JAN-79 LOGICAL COMPARE OF TWO I*2 WORDS N = ICMP( I1, I2) WHERE N=0 IF I1=I2 N=1 IF I1>I2 N=-1IF I1 STR2, RETURN 4. MODE 2: FOR LGTH OF SHORTER STRING, IF STR1 = STR2, RETURN 8. IF STR1 <> STR2, RETURN 0. MODE 3: IF STR2 A SUBSTR OF STR1, RETURN THE STARTING POSITION IN STR1 WHERE STR2 APPEARS. IF NOT, RETURN 0. MODE 4: DEFINING A DELIMITER AS ANY ASCII CHAR .NE. (0-9) OR (A-Z) IF STR2 IS A DELIMITED SUBSTR OF STR1 (DELIMITERS NOT REQUIRED AT START OR END OF STR1), RETURN THE STARTING POSITION IN STR1 WHERE STR2 APPEARS. IF NOT, RETURN 0. NOTE: NMWS SEQUENCE S1A,...,S2L IS REQUIRED BY SETUP CODE BELOW. PAGE 10 ARAP ARAP.OLB PAGE 10 LCKCV.MAC -- CHECK BIT VALUE AUTHOR: LEN DATE WRITTEN: 23-JAN-78 FUNCTION LCKCV (IBIT, IVEC) IBIT = BIT TO CHECK (STARTS AT 0) IVEC = BIT STRING RETURNS 1 IF SET, 0 IF NOT MODFD.MAC -- MODIFY FDB FOR 0 BLOCK PRINT FILES AUTHOR: J. LEONARD DATE WRITTEN: 03-NOV-77 CALL: CALL MODFD (LUN, NBLKS) WHERE: LUN = FILE'S LOGICAL UNIT NBLKS = NUMBER OF BLOCKS ALLOCATED (FROM DIR/FU) PAGE 11 ARAP ARAP.OLB PAGE 11 MONTRY MONITOR TRACE IN & TRACE OUT ROUTINE USED WHEN DEBUGGEG NOT IN MONTRI CALLED BY FORTRAN CALLABLE ASSEM RTNS. JSR R1,MONTRI .BYTE NPAR ;# PARMS EXPECTED BY ASSEM RTN ;NPAR IS -1 IF VAR NUM OF ARGS MONTRI POPS R5 FOR NON VARIABLE PARM LIST .BYTE 0 ;RES FOR FUTURE USE .RAD50 /ASSEM NAME(MUST BE 2 WORDS/ MONTRI WILL BUILD TRACE BACK CHAIN AND SAVE REGS MONTRO WILL RESTORE REGS(MONTRO IS CALLED INSTEAD OF ASSEM ROUTINE DOING AN RTS PC TO RETURN) POPS TRACE BACK CHAIN RESTORES REGS 0-4 MONTRF FUNCTION RETURN-SAME AS MONTRO EXCEPT DOESN'T RESTORE R0 NSCOPE.MAC - FIND TERMINAL SPEED AUTHOR: LEN DATE WRITTEN: 20-DEC-78 N = NSCOPE (LUN) WHERE LUN = LOGICAL UNIT NUMBER OF TERMINAL N = 0 IF NOT SCOPE, 1 IF IT IS PAGE 12 ARAP ARAP.OLB PAGE 12 OPFID.MAC --OPEN ON FILE ID AUTHOR: J. LEONARD DATE WRITTEN: 12-MAY-78 CALL: CALL OPFID (LUN, ID, NERR) WHERE: LUN = FILE'S LOGICAL UNIT ID = 3 WORD FILE ID NERR = FCS ERROR CODE CALL STBLK (BUF1, BUF2, NCH) WHERE - BUF1 = INPUT BUFFER BUF2 = OUTPUT BUFFER (BUF1 CAN BE THE SAME AS BUF2) NCH = # OF CHARACTERS TO STRIP OUT BLANKS ALSO REFER TO STBLK.FTN FOR TRNASPORTABLE VERSION BLOCKED DISK READ WRITE CALL X1DR (ID, NR, NWR, IOAR) WHERE - ID = 6 WORD ID BLOCK (SEE X1LU) NR = RECORD # TO BEGIN READING NWR = # OF I*2 WORDS TO READ IOAR = BUFFER AREA TO ACCEPT DATA CALL X1DW (ID, NR, NWW, IOAR) WHERE - ID = 6 WORD ID BLOCK NR = RECORD # TO BEGIN WRITE NWW = # I*2 WORDS TO WRITE IOAR = OUTPUT AREA SAME AS ABOVE BUT DATA IS TRANSFERRED FROM IOAR TO THE BUFFER AREA AND EVENTUALLY TO DISK ** NOTE ** NR IS ASSUMED TO BE I*2 UNLESS BIT 0 IS SET IN ID(5). SEE X1LU. PAGE 13 ARAP ARAP.OLB PAGE 13 X1EFBY.MAC -- FETCH EOF BLOCK NO. AND FIRST FREE BYTE. AUTHOR: J. LEONARD DATE WRITTEN: 02-NOV-78 CALL: CALL X1EFBY (LUN, ILOBLK, IHIBLK, IFBY) WHERE: LUN = FILE'S LOGICAL UNIT ILOBLK = LOW ORDER WORD OF EOF BLOCK IHIBLK = HI ORDER WORD OF EOF BLOCK IFBY = FIRST FREE BYTE PAGE 14 DFX ...DFX is an RSX program to do absolute disk patches on to your current SY: disk. calling sequence is via a MCR>DFX In response to "ENTER DISK BLOCK #" type block number in octal or "E" to exit to RSX. The block will be read in and can be displayed by the "L" command. display is on LUN 6 Note that LUN 2 is used for disk reads and LUN 4 for disk writes, as a protective measure LUN 4 is assigned to pseudo device XX: and must be re-assigned by the user before to enable write-back Also note that LUN 6 is used for full block listings. it is initially set to TI: but can be re-assigned to a disk, and will be in the users UIC as "DFX.DAT" In response to "DFX>" prompt, type L to list referenced block W to write the currently referenced block back onto disk N to read the next block R to reread the current block (overwriting current buffer) B to read the previous block F for full-word addresses (defaults to byte addresses) H for half-word (byte) addresses in block T to type out the block as ascii text S to set/clear flag for spooling output file to LP0: if LUN 6 is a disk, the file will be spooled on exit or when the spooling flag is cleared by the operator K to calculate checksum of first 255. words of block E to exit to the monitor there are 4 M(odify) type commands, where M=the byte offset of the buffer word to be listed/modified Note that for M commands, M must be even, 0 <= M < 1000 M/000000 change buffer word to the octal value 000000 M,LLL change buffer word to rad50 vaLue of "LLL" M;AA change buffer word to ascii value of "AA" M: display buffer word in octal, rad50 and ascii there are 4 commands which alter the ablsolute block number D,N to change default block number for read and write to N with- out changing the contents of the buffer in core. this should permit moving data from one block to another. A,N to read and list block N (N absent implies next block) C,N to read and list all blocks up to and including block N. (N absent implies to end of disk.) P,N changes the high-order block number from the disk. no I/O will be done, but the block number will be copied from the high-order and low-order blocks to relative words 400 & 401 (byte offset 1000 & 1002) past the IO buffer where the single-word examining commands can see them. PAGE 15 DSCCPY DSCCPY.DOC DSCCPY - FORTRAN program to copy just a few files from a DSC tape without restoring the entire volume. William D. Burton, Jr. Texas Research Institute of Mental Sciences 1300 Moursund Houston, Texas 77030 (713) 797-1976 ext 501 Modifications: 3-Nov-81, WB-005, Put confirmation of files copied on LUN-5 so it can go to some other device. Add count of files copied. 2-Nov-81, WB-004, Add option to select files to be copied on the basis of creation date. 28-Aug-81, WB-003, Do not unload after rewind 22-Jun-81, WB-002, Fix overwrite of files 22-Jun-81, WB-001, Allow 1600 BPI tape. I needed a program to copy some files from a DSC (Disk-Save-and- Compress) tape from a large disk onto an RK-05. DSCCPY is the result. It was written in FORTRAN (Fortran-IV-Plus v 2.51) and MACRO and has run under RSX-11M V3.0 (sic) and IAS. USING THE PROGRAM: This program is controlled by user responses to prompts. It will not accept indirect command files). The input tape(s) are UNMOUNTED. The reels of a multi-reel set do not have to be read in sequence PROVIDED that the data file being copied does not cross reels. 1. The Input tape must be UNMOUNTED 2. The Output Disk must be MOUNTED. 3. Run DSCCPY and answer the questions: a. prompt = ENTER TAPE INPUT UNIT answer = input tape device name (e.g. MT1:) program action = Assign Fortran LUN 3 to the specified device. Attach device and rewind. answer = control-Z program action = exit. b. prompt = TAPE DENSITY (800 OR 1600 BPI) answer = Integer 800 or 1600 for density of tape. default is 800 bpi. program action = Set density of tape using QIO. PAGE 16 DSCCPY DSCCPY.DOC (continued) c. prompt = DSC TAPE FILE NAME answer = 12-character file name specified when tape was created. a wildcard (*) matches any name. A wild character (?) matches any single character. answer = a null input (carriage return only) inhibits the search for a named DSC output file. This is the response which must be used if the first reel of a multiple reel tape is NOT being read. program action = Search for the ANSI HDR1 record with the specified label. If not found on the current reel, return to step 3a. d. prompt = OUTPUT DEVICE AND UIC DDU:[UIC] answer = Disk output device where the restored file is to be put. No wildcards. The defaults are the normal Fortran defaults for LUN 4. program action = Check for the desired volume being mounted. e. prompt = FILE TO BE COPIED answer = [OWNING UIC]filename.ext;version of the file to be located and copied. Any field can be wildcard (*) or contain wild-characters (?) answer = /FI:filn,filsn this allows the user to copy a single file using its original file-number (filn),file-sequence-number. NO wildcards or wild-characters. program action = Search for the file specified and copy to the output. If the file is not on the current reel of a multi-reel tape, a prompt for the new reel will be issued. If the file is not in this volume (i.e. an ANSI EOF record is found) an error message is output. If the file already exists (same Directory, name, extension, version) an error message is produced and the file is not copied. f. prompt = FILENAME CONTAINS WILD CHARACTERS, COPY MULTIPLE FILES? answer = Y program action = multiple files will be copied. Prompt (g) will be produced (creation date selection) answer = N program action = Only the first file which matches will be copied. No selection on creation date. NOTE the file copied will not necessarily be the one with the highest version number. PAGE 17 DSCCPY DSCCPY.DOC (continued) g. prompt = MULTIPLE FILES WILL BE COPIED SELECT BY CREATION DATE? [BEFORE: ON: AFTER: DD-MMM-YY] -ONLY IMPLIES NO DATE SELECTION ? answer = OPTION: dd-mmm-yy where OPTION = BEFORE, ON, AFTER dd-mmm-yy = date OPTION must be followed by either a : or a space. No other spaces are allowed. Date must be in the form specified. program action = file header of file with matching name will be checked to see if the creation date falls in the range implied by the option. If it does, the file will be copied. answer = (null line) program action = No selection by creation date. h. prompt = WARNING, FILE ALREADY EXISTS FILENAME: DO YOU WANT TO: C COPY ANYWAY (OVERWRITE) S SKIP COPYYYING THIS FILE N CREATE A NEW VERSION answer = C, S, or N default is to skip program action: C - program will overwrite the old file. S - program will skip the copy (the new input file) N - Will cause the version number of the offending new file to be stripped off. Then the file will be open for output, creating a new "most recent" version. PAGE 18 DSCCPY DSCCPY.DOC (continued) NOTES AND LIMITATIONS: 1. This program has been used on both 7-track and 9-track TM-11 look-alike drives. Routine NXTAPE was changed to allow 1600 bpi tapes. 2. If DATA OVERRUN errors (-13. IE.DAO) occur, the size of the tape input buffer can be increased using PARAMETER NRLTH= newsize in the main program. The buffer should never be less than 1040. bytes. 3. Error checking on the prompt input filenames is very primitive. Only a simple check on the syntax of the file specifier is done. Illegal characters in the fields are not detected. This will lead to "NOT FOUND" type errors. 4. There is no verify of the copied data. 5. The /FI:filn,seqn command does not accept wildcards or wild characters 6. Because directory files are not guaranteed to be on the same reel as the file being copied, and I didn't want to have to read the whole DSC volume, I chose to use the file identifier as found in the files-11 file header. If a file has been re-named before being DSC-ed this file identifier will not match the directory entry. The /FI: option can be used to find the file, given a DSCDIR listing of the directories. 7. As much information as practical of the original file-header is preser- ved with the copied file. Because I did not want to do the copy with the index-file UNLocked not all information is preserved. The following items from the file header are preserved during the copy: file name, extension, version space allocated and contiguous/non-contiguous indication end-of-file pointer record attributes The following information is NOT preserved: DIRECTORY uic OWNING uic creation date and time last update date and time mapping PAGE 19 DSCCPY DSCCPY.DOC (continued) INSTALLING DSCCPY DSCCPY was originally compiled under F4P (version 2.51). It uses some MACRO-11 routines for string and FDB manipulation. The distribution includes the following files: DSCCPY.FTN -- Fortran main program DSCFTN.FTN -- Fortran subroutines DSCMAC.MAC -- Macro-11 subroutines DSCCPY.CMD -- Task build command file DSCCPY.DOC -- This document. Compile or Assemble as appropriate, the 3 source files. Edit the task build command file to reflect your configuration if needed. The device assignments for luns 3 and 4 are changed in response to user prompts at run-time. PAGE 20 DSCDIR DSCDIR.DOC DSCDIR - FORTRAN PROGRAM TO PRODUCE A DIRECTORY OF DSC TAPES. MODIFICATIONS: 28-Aug-81, WB-004 do not unload tape after rewind 11-Jun-81, wb-003 fix error with empty and short directories 10-Jun-81, WB-002 fix problems with error on .DIR files 10-Jun-81 WB-001 Allow 1600 bpi tape William D. Burton, Jr. Texas Research Institute of Mental Sciences 1300 Moursund Houston, Texas 77030 (713) 797-1976 ext 501 This file describes the program DSCDIR, a FORTRAN-IV-PLUS program which produces a directory of tapes written by DSC (Disk-Save-and-Compress) Utility. It has worked on both RSX and IAS systems. INSTALLATION: 1. Distribution of DSCDIR consists of: DSCDIR.FTN - Main program and subroutines DSCDIR.CMD - Task build command file DSCDIR.DOC - This file 2. Compile the main program DSCDIR.FTN 3. Edit the task-build command file for your installation e.g. resident libraries etc. OPERATION: 1. The DSC tape to be scanned is UNMOUNTED on fortran LUN-3 DSCDIR uses direct QIO reads (subroutine RDTAPE). The program does NOT require reading all reels of a multi-reel tape set. 2. Run DSCDIR and answer the questions. DSCDIR will not accept indirect command file input. a. prompt = INPUT TAPE SPECIFIER [DDU:] answer - name of the tape device holding DSC tape. (e.g. MT1:) b. prompt = TAPE DENSITY (800 OR 1600 BPI)? [I] answer - density of input tape, integer 800 or 1600 default is 800 bpi. c. prompt = PRINT CONTENTS OF DIRECTORY FILES [Y/N] answer - Y if a listing of the contents of the Files-11 disk directories is wanted. N to suppress this list. PAGE 21 DSCDIR DSCDIR.DOC (continued) d. DSCDIR will read the tape and print a summary of: 1) ANSI standard file labels (80 characters) 2) FILES-11 file headers file-id file-name, extension, version creation date and time 3) DSC initialization information (first reel of DSC tape set only) LIMITATIONS: 1. The predecessor of this program was used in checking out the file-restoring program DSCCPY. This program should be fairly robust. 2. If DATA OVERRUN errors occur (error code -13. IE.DAO), the program buffer size can be increased by changing PARAMETER NRLTH= to the desired size. NRLTH should never be less than 1040. bytes. 3. If multiple tapes are directoried out of sequence, FALSE error messages FILE NUMBER OF DATA BLOCK DID NOT MATCH will be printed these messages can be ignored. PAGE 22 DSCFORMAT Disk Save and Compress (DSC) Tape Formats 1-April-81 I. INTRODUCTION This note describes what I have learned of the format of DSC produced magnetic tapes. The information presented here is to be considered prelimi- nary and subject to revision. The Stand-Alone DSC V2 was used to create test tapes for this project. Bill Burton Texas Research Institute of Mental Sciences 1300 Moursund Houston, Texas 77030 (713) 797-1976 ext 501 PAGE 23 DSCFORMAT II. DSC TAPE STRUCTURE Basically, DSC tapes are ANSI standard version 1 labeled magtapes. Standard version 1 has been superceeded by version 3 (ANSI X3.27-1978). Some of the label records are non-conforming or undefined in the version 3 standard. The DSC tape volume consists of ANSI labeled volume and header labels surrounding DSC formatted data records. Record Number Length Contents 1 80. VOL1 label record volume identifier derived from the output file name given in the DSC command line for the first output file. a. Truncated to 4 characters if necessary b. Padded to 4 characters using the character X c. Sequence number, 2 characters 01 for first reel of a set 02 for second, etc. d. Other information is documented in ANSI Standard Manual or RSX-11 I/O Operations Manual. 2 512. Dummy bootstrap block which produces the message "This volume does not contain a hardware bootable system". 3 80. HDR1 label record a. File name specified in DSC command line b. Volume identifier from VOL1 record 4 80. HDR2 label record a. An undefined record code (U) is non-standard b. Logical record length 2064 bytes c. Physical record length maximum 2064 bytes d. The character M in byte 37, non-standard e. Buffer offset 00 in bytes 51-52. 5 Tapemark 6 1040. First DSC formatted record, contains a. 8 word (16 bytes) DSC header with code=40 b. 512. bytes of DSC Bookkeeping information (documented in section IV) c. 512. byte Files-11 file header for the file (1,1) [0,0]INDEXF.SYS;1 7. 1040. DSC Data record should contain initialization data for disk structure, 2 virtual blocks worth. 8. 2064. DSC Data record More initialization information for virtual block 377,177777. PAGE 24 DSCFORMAT 9. & up 528. (or 1040. or 1552. or 2064.) Contain DSC data records with DSC codes 1, 2, or 4 The details of these records are in section III. DSC copies files to the output tape in file-number order. For each input file on the disk there is 1 type 2 record (of unknown function) 1 type 4 Files-11 Header record as many type 1 data records as needed to hold all virtual blocks allocated to the input file. At the end of data from a disk volume, there will be Record number Length Contents N tapemark N+1 80. EOF1 record Identical to HDR1 except bytes 55-60 now contain the number of physical tape records between HDR2 and EOF1. N+2 80. EOF2 record Identical to HDR2 record N+3 tapemark N+4 tapemark, if this is the end of the tape volume OR 80. HDR1 for the next output tape file created using DSC /AP switch. If the tape is filled, (ie reaches the End-of-Tape foil marker) the EOF1 and EOF2 records will be replaced by EOV1 and EOV2 records. The following reel in the set will start with a VOL1 label with the output volume name incremented by 1. The structure of all subsequent reels is the same as described above for the first reel, except that data records start immediately. There will be no DSC initialization records (6, 7, and 8. above) on subsequent reels. It is possible for data from a disk file to be split across two reels, and the data for a file can be separated from its DSC header records or Files-11 header record when changing reels. PAGE 25 DSCFORMAT III. DSC DATA RECORD FORMAT Within the labeled file, DSC writes its own format records. These records contain: a. An 8. word header b. 1, 2, 3, or 4-512. byte logical data blocks. DSC header Format word 1 Length of the data portion of the record, excluding ALL DSC specific information. word 2 DSC record-type code indicating the type of data in the data portion of the record. code = 1 Disk data record(s), images of input disk blocks 2 Prefix information. I have not fully decoded the data in these records. May have some filename and extent information. 4 Files-11 file header (records of code 4 only have one 512. byte data block). 40 Special DSC initialization record. a. 512. bytes of initialization information see section IV. b. 512. byte Files-11 header for INDEXF.SYS words 3-4 For type 1 records, these words contain the Virtual Block Number (VBN) of the of the first logical block in the DSC data record. The low order part of the VBN is in word 3, the high-order part is in the low byte of word 4. I have not fully understood the use of these words for the second data record for the INDEXF.SYS file. word 5 The file number this record applies to word 6 The file sequence number this record applies to. words 7-8 Always seem to be zero. PAGE 26 DSCFORMAT IV. DSC INITIALIZATION RECORD This record contains the usual 8-word DSC header with a code of octal-40 in word 2. The data portion of the record contains 512. bytes of DSC control information plus the 512. byte Files-11 file header for (1,1) [0,0]INDEXF.SYS;1 The DSC control information is formatted within the record as follows: Bytes Contents 1.- 12. DSC Output name from the command line, ASCII padded with spaces 13.- 24. Input device name (e.g. DK1), ASCII, padded with spaces 25.- 36. ? null 37.- 48. Input volume name, ASCII, padded with nulls 49.- 52. ? null 53.- 54. ? 1 55.- 58. Number of blocks on the input device, binary 59.- 62. Number of blocks in use on the device, binary (not including bad blocks) 63.- 66. Number of files in use on the device, binary 67.- 68. ? 69.- 70. ? null 71.- 72. ? Number of blocks allocated to index file 73.- 74. ? 75.- 76. ? 77.- 78. ? 79.- 80. ? 81.- 82. ? 83.- 84. ? 85.-510. ? null 511.-512. checksum Items marked with ? are items I have not identified. PAGE 27 DSCFORMAT V. DSC CODE 2 RECORDS One of these records preceeds each files-11 file on the DSC tape DSC header word 1 = 512 word 2 = 2 word 5 = file number of the files-11 file word 6 = file sequence of the files-11 file. DSC data block, 512. bytes words 1-3 the string BACKUP word 5 The number of bytes in the name string words 6.. The file name string, in the form DDU:[126,342]filename.ext;ver the UIC 126,342 seems to be constant,regard- less of what the source or directory uic was. word 46. Number of blocks allocated to the file word 52. (same as word 46.) word 67. Owning UIC group number word 68. Owning UIC member number. There is some more information, but I have not determined what it is, it was not necessary for restoring files. VI. DSC FILES-11 HEADER RECORD One of these records immediately follows the DSC code 2 record and contains: DSC header word 2 = 4 code for files-11 header record word 5 = files-11 file number for this file word 6 = files-11 file sequence number for this file. The data portion of the record contains the 512. byte files-11 header block for the file. It is an exact image of the header as it was on the disk, including the map area. PAGE 28 FAC Files-11 ACtivity reporting program F11ACt is a sytem performance measurement program for taking a snapshot of files-11 ACP activity on a running IAS or RSX-11D system. It was originally developed to verify FILES-11 ACP data structures "on the fly", but it has since evolved into a general purpose file system tuning tool. The program produces a report of currently accessed files for each file- structured device known to the system,with statistics on ACP data structure and memory utilization. F11ACt can optionally produce a report on a list of specific devices, or on all devices serviced by a given ACP task. this in- formation can be used to formulate optimal strategies for assigning devices to ACPs on a multiple-ACP system, for determining size requirements for the ACP internal fcb storage area,the size of fcpcom, the size of the directory LUR cache, and so on. See file example.lst for an example of the output produced by the following commands: command line syntax: [outfile][/-APpend][/SPool][/FILES][/PRiority:N] = [/ACP:xxxxxx] or = [device[/FILES]],... /APpend Open outfile for append (default), else create outfile /SPool spool outfile (default is /-SP) /FILES List attributes of all files open on all devices if this switch appears on output side of command line List attributes of all files open on specified device if this switch appears on input side (default is /-FI in both cases). /PRiority:N ACP run priority is N (decimal) (default is 220.) /ACP:xxxxxx Gather statistics for all devices serviced by the named ACP. If this switch is specified on the input side, a device list may not be specified. An empty command line is equivalent to the following defaults: F11ACt> TI:F11STATS.LST/APpend/-SPool/-FILES/PRiority:220. PAGE 29 FDU NEW UTILITY A dump program differing from DEC's dump, which can only output in one format at at time. FDUmp lists output in OCTAL,ASCII, and RAD50 on the same line of print FDUmp supports 2 switches /A this specifies the offsets for each line to be listed relative to the beginning of the file. that is, block 1 starts at '000000, block 2 starts at 1000, block 3 at 2000 ....etc. this is useful for looking at files which contain linked lists, like [1,4]SPRQUEUE.SYS. (Normally each block is listed realative to 0.) /BL:N:M List blocks n thru m inclusive or /BL:N List blocks n thru end of file inclusive Calling proceedure: MCR>FDU filespec or MCR>FDU FDU>filespec where filespec is a file name of the form DDN:[GGG,UUU]NAME.TYP;VERS output will be directed to LP0: PAGE 30 FHD FHD is a program to list the file header of a given file Primary purpose is to list all the pieces of the file to determine how fragmented the file is if it is a large data file, and to determine which absolute blocks on the disk the file occupies, (if troubles occur with the disk) After listing routine information from the file header, fhd lists each piece of the file, reporting on: Number of blocks (decimal) First block # (absolute disk block number, 2 word, octal) Last block # (absolute disk block number, 2 word, octal) Fhd also reports if the header had to be extended (by using an extension file header) and lists the unique file id (FID) for the extension file calling proceedure MCR>FHD nnnnnn,mmmmmm where nnnnnn,mmmmmm is the file's (unique) FILE ID (obtained via a PIP or SRD directory using the "/FU" switch) PAGE 31 FLB Find Logical Blocks A Contiguous Block Identification Utility 15-FEB-81 (Revised 19-JUN-81) J. Bradley Flippin Raytheon Service Company 2341 Jefferson Davis Highway (Suite 1200) Arlington, Virginia 22202 Phone (703) 685-2200 PAGE 32 FLB FLB --- A contiguous block utility program PAGE 2 Program Description Background: Disk cartridges and packs are structured into tracks and sectors. these sectors, each of which contains a block (or partial block) of data, are used by the operating system to store files. Under RSX-11M, this file structure is known as FILES-11 and consists of one (or more) header blocks and any number of associated data blocks. The data blocks are assigned by the FILES-11 Auxiliary Control Processor (F11ACP) to the respective header by means of map pointers. Basically, as the system needs blocks, they are allo- cated in a systematic way: Always from the bottom up! This process continues until the file is full. Deleting files results in the de-allocation of the respective blocks as in- dicated in the file header's map area. This makes them ava- ilable for the next user. As time progresses, it can be seen that the disk can become a "shotgun" of randomly as- signed data blocks. This fragmentation may eventually have an adverse affect, particularly when a task requires large blocks of contiguous space, such as SORT which requires them for its working files. The scattered blocks can be consolidated (or com- pressed) by using the Disk Save and Compress (DSC) utility. However, this requires that the disk be copied to another media and then re-built on the original media. If tape is used, or only a few files are destroying the contiguous space, then a faster way would be to free up the contiguous space by moving the guilty files. This would require searching every header and then searching all its map po- inters to see if any of their data blocks are in the affect- ed area. This is a long and difficult manual process. FLB, however, will find the guilty files for you. BITMAP.SYS: The one system file which holds the key to which blocks are in use (allocated) and which are available for use is BITMAP.SYS which is located in the null directory [0,0]. It is a file in itself. It has a header which maps one Storage Control Block (SCB) and "n" bitmap blocks, each capable of "mapping" 4096 decimal blocks. Thus, the floppies (RX02) use one bitmap block where the RK07 has 14 bitmap blocks (not counting the SCB which is always VBN #1). To use the FLB utility, all one needs to do is dump BITMAP.SYS and use it as a roadmap to find and identify the desired blocks. The space is freed by the simple process of moving them. The F11ACP always assigns the new blocks starting at the lowest numbered blocks. This effectively moves the files to the front of the device, unless, of PAGE 33 FLB FLB --- A contiguous block utility program PAGE 3 Program Description course, the device is already full. Assembling and Task Building FLB: Building FLB is relatively straight forward. The source media should contain the following files: 1. FILES.MAC;1 dated 15-FEB-81 (Source file) 2. FILES.COR (The latest correction file) 3. FILES.CMD (A command file to build FILES) 4. MOVE.CMD (A command file to move guilty files) 5. FILES.DOC (This documentation file) 6. COPY.CMD (A command file to make copies of the source media) To build FLB, simply copy the source to your media with @COPY then run @FILES. The file will ask whether or not you want a listing. If yes, it will put FILES.LST on SY:. When installed, the task will have the name "...FLB". PAGE 34 FLB FLB --- A contiguous block utility program PAGE 4 Program Description How to Use FLB: The following procedure is recommended (all numbers are octal unless otherwise indicated): 1. The device in question must be mounted. 2. Determine the free space available by using PIP. Enter: PIP DM:/FR (or FREE, if TDX is installed). If the number of free blocks exceeds by a large am- ount the number of contiguous free blocks, then FLB will be of some help. If not, then moving the files may simply move them to higher block numbers. 3. Dump the bitmap by entering: DMP BITMAP=DM:[0,0]BITMAP.SYS 4. Examine the bitmap dump, looking for the largest grouping of "1" bits (ie: l777777 indicates all 16 decimal blocks represented by that word are avail- able). Generally, these will be towards the end of the device. Note that the last block generally shows a large portion of allocated blocks towards the end. This is because most devices do not have an integral multiple of 4096 decimal blocks. 5. FLB can now be used to identify the desired files. Simply enter the search parameters by means of input switches. Figure 1 shows a sample output. the following are examples of various command line inputs: 1. Show all files containing blocks in virtual block number 15 of BITMAP.SYS: FLB TI:=DM:/BLK:15:15 2. Print a listing of the file using a specific LBN (ie: 4200)-(Note that the /LBN switch utilizes double precision): FLB LP:=DM:/LBN:0:4200:0:4200 3. Spool a file "FILES.LST" on SY: listing all files represented by the 16 bits of word 10 of BITMAP VBN 15: FLB =DM:/BLK:15:15/WD:10:10 4. Search the BITMAP starting with block 15 and extending to the end of the device: PAGE 35 FLB FLB --- A contiguous block utility program PAGE 5 Program Description FLB TI:=DM:/BLK:15 5. Search the BITMAP to the end of the device starting at a specific word: FLB TI:=DM:/BLK:15/WD:20 6. The affected files can now be moved. Go to the proper directory (UIC) and use PIP /NV/CD=filename.type;ver. Be sure to use the spec- ific file version. Once the file has been moved, the specific version can then be deleted (The same thing can be accomplished by using the MOVE command file). PAGE 36 FLB FLB --- A contiguous block utility program PAGE 6 Program Description Problems: Problems may be encountered during the use of FLB. Usually then can be resolved. The following are a few exam- ples (references are to the Utility Manual [AA-H268A-TC]): 1. All headers may not be listed in a UFD. This is evident when a filename.type;version cannot be found with PIP [*,*]. Solution: Run VFY with the /LO switch (see Section 13.3.5). This will find the "lost" file(s) and place them in the lost files directory [1,3] where they can be properly deleted. 2. All blocks may not be mapped to a header. This is evident when files does not list a culpret, but the bit is shown as set in the BITMAP.SYS Dump. Solution; Run VFY with the /RE switch (See Section 13.3.7). 3. Finally, it may be a bad block. This is evident when the FILES listing contains [1,1]BADBLK.SYS as one of the first entries (headers are serached in sequence - BADBLK.SYS is header number 3). Do not confuse "last track" protection provided to last track devices (ie: RK06/7, RL01/02, and RM02/03) with actual bad blocks. This can be verified by dumping the header of BADBLK.SYS. The first entry in the map area will show blocks mapped at the end, then the actual bad blocks are mapped individually. (See Section 9.3.1.2). If it is a bad block, there is no solution, except to get a new disk. PAGE 37 FLB FLB --- A contiguous block utility program PAGE 7 Program Description Notes: 1. Remember, all UIC's in the FLB listing are those of the OWNER. Generally this will also be the di- rectory in which they are listed. If not, then search for them using a wildcard PIP command (ie: PIP [*,*]filename,type;ver. 2. Special conditions apply to UFD's because the File ID is contained in the MFD. A UFD is identified by a filespec similar to: DM0:[001,001]007007.DIR;1. The proper procedure here is: 1. Move any files in the UFD to another UFD (using the /CD switch if desired). 2. Delete the files from the original UFD. 3. Delete the UFD (ie: PIP [0,0]007007.DIR;*/DE). 4. Create a new UFD with the same UIC (ie: UFD DM:[7,7]). 5. Run FLB again to ensure it has not put the new UFD in the same area of interest (or dump its header and check the map pointers). 6. Finally, copy back the output files to the new UFD (using the /CD switch again, if desired). 3. If the file is an installed task, then it must be removed (REM) and re-installed (INS) after the move, or the system may crash when it is called. (Don't forget to do this to your task image by run- ning VMR). 4. For additional information see the MACRO source listing. PAGE 38 FLB FLB --- A contiguous block utility program PAGE 8 Program Description Example: DM0:[001,001]BADBLK.SYS;1 <------ (Indicates a bad block) DM0:[104,060]EDITOR1.TMP DM0:[111,142]VSCAT.OBJ;3 DM0:[111,141]SHP733.LST;1 DM0:[111,064]AOSTUDY.TSK;2 DM0:[111,142]VSCAT.LST;10 DM0:[111,142]VSCAT.SKL;3 DM0:[111,141]SHP732.LST;1 DM0:[106,130]REPORT.FTN;6 DM0:[111,064]AOSTUDY.TSK;1 DM0:[104,060]KWIC.LST;25 DM: = 53790. BLOCKS SPAN: 4096. BLOCKS LO LBN: H:000 L:130000 = 45056. HI LBN: H:000 L:137777 = 49151. FILES FOUND: 11. ELAPSED TIME: 00:01:24 LP:=DM:/BLKS:15:15 Figure 1 - Example of FLB run on an RK07 PAGE 39 FLB FLB --- A contiguous block utility program PAGE 9 Technical Description INTRODUCTION The following technical notes are provided for those who desire to know what is happening within the FLB pro- gram References are to the I/O Operation and Reference Manu- al (AA-2515D-TC). Details of the command line processng, FCS, and the simpler routines are not provided. The basic assumption of FLB is that it will be work- ing on a FILES-11 structured device. This means that it will be looking for certain things in certain places. Specifically, it assumes that the device contains the stan- dard five system files (only the first one is accessed by FLB). #1 - INDEXF.SYS #2 - BITMAP.SYS #3 - BADBLK.SYS #4 - 000000.DIR #5 - CORIMG.SYS Command Line Processing The command line includes two output switches and three input switches. The output switches are /ID (to provide the program version number) and /SP (to spool the output). The defaults are /-ID and /SP, respectively. The three input switches are /LBN, /BLK, and /WD. The /LBN switch permits the user to specify a logical block number (or numbers) directly. The format is standard double precision (ie: /LBN:0:100:0:100 = LBN #100 only). The other switches are designed to match the BITMAP.SYS dump and are mutually exclusive with the /LBN switch. The /BLK switch may stand alone, but the /WD switch requires the /BLK switch. The output switches are first validated to ensure the above logic has been observed. Next the switch values are validated by "VALIDATE SWITCH VALUES." Here a stop value of zero is replaced by the SIZE parameter which was extracted from the device's Home Block by the Get LUN (GLUN$) direc- tive during the parsing of the input filespec. This value (minus one) is set into the stop LBN if it is not present (or equal to zero). The /BLK switch is validated next to ensure that is is greater than one and that the stop block is not less than the start block value. The /BLK switch was designed to per- mit the user to enter the octal block numbers from a BITMAP.SYS dump directly. Thus, the /BLK validation routine esures that the Storage Control Block (VBN #1) is passed. PAGE 40 FLB FLB --- A contiguous block utility program PAGE 10 Technical Description Finally, the /WD switch is validated by ensuring that it is less than 512 (decimal), that it is an even number (word aligned), and that the top value is less than the start value only in those cases when the start/stop /BLK va- lues differ (interblock search). Once the switches have been logically verified and the values validated, then the actual start and stop LBN is cal- culated. If the /LBN switch was used, then the "GENERATE THE LBN VALUES" routine is bypassed. Otherwise, the /BLK values are converted to LBN values by the equation shown on the listing. The /WD values are then added or subtracted from the resulting LBN's as required. Processing The first action, after deciding that the command line was proper, is to retrieve the Home Block, which is LBN #1 on the device. This is accomplished by the FCS procedure "RETRIEVE HOME BLOCK". The INDEXF.SYS file is non- conven- tional, in that the offsets F.HIBK (the highest block allo- cated to the file) and F.EFBK (the end-of-file block) are both zero. These must be set to their logical values so the program can scan the headers and detect an EOF condition at the appropriate time. This is acommplished by opening the file with the statisitics block, as described in Paragraph 3.1.2 under file option 3.d (Page 3-11). The statistics block is shown in Figure H-1 on Page H-1. Once the INDEXF.SYS header file FDB has been reset, then the home block is read into the buffer region named "HEADER." The important values in the home block are the first two bytes (H.IBSZ) which indicates the size of the index file bitmap, ant the next four bytes (H.IBLB) which contain the LBN of the first block of the index file bitmap in dou- ble precision format. These are important because they pro- vide the physical location (LBN) of VBN #3, which is the start of the header bitmap and its length. Adding the two together provides the LBN of the first header (1,1) which happens to be INDEXF.SYS. The program is now set to scan the headers. The "RETRIEVE A HEADER BLOCK" routine reads each header sequentially. Offset H.FNUM is checked each time. If it is zero, then it is a deleted header and the next one is read. If it is not zero, then it begins searching the map pointer region of the header. Each file header contains a map area which consists of, among other things, an offset M.USE (one byte) which is a count of the number of map pointers in use. The maximum value is 102 pointers (The actual value is the number of PAGE 41 FLB FLB --- A contiguous block utility program PAGE 11 Technical Description words used or twice the the number of pointers used). If this value is null, then it is either a null header or the program has checked all of its pointers. The secton of the header used in the searching is the retreival pointer sec- tion which starts at offset M.RTRV. To find this offset, the program steps past the header section (S.HDHD), the identification section (S.IDHD), to the start of the retri- eval section (M.RTRV) (See the equated symbol MPTR in the listing). Each pointer consists of two words (four bytes). The first byte contains the high order eight bits of the 24 bit LBN. Byte two contains the count field and bytes three and four contain the 16 low order bits of the LBN. Each pointer can map up to 256 (decimal) contiguous blocks. The value of the count is actually n-1, thus a zero points to one block, while a value of one points to the first of two contiguous blocks. The "SEARCH MAP POINTERS" routine checks the MUSE location first, exiting if it contains a zero. Otherwise, it extracts the two word map pointer and divides it into a count filed and a double precision LBN, then calls SEARCH which decrementes until it reaches zero (or a match is found) at which time the next header is read. The actual search routine is contained in "SEARCH FOR A MATCH." It performs a search based on the following logic: 1. If the LBN of the first block of the pointer is below the starting LBN, then there is no match pos- sible and it exits. 2. If it is equal, then there is a match of at least the first block. The OUTPUT routine is called which outputs the full filespec to the output FDB. 3. If it is greater than the first LBN of the pointer, then no immediate conclusion can be reached, so the LBN must be checked against the stop LBN. 1. If it is LT/EQ, then a match has occurred. 2. If NE, then the LBN of the last block in the pointer's contiguous group must be calculated by adding the count field to the pointer's LBN. 1. It it is LT/EQ, then a match has occurred. 2. If not, then it is outside of the range and the routine exits. PAGE 42 FLB FLB --- A contiguous block utility program PAGE 12 Technical Description The above process is repeated for each header until an EOF condition is reached, at which time the summary is out- putted. Correction File Corrections to the orginal source file will be made by means of a correction file to be used with SLP. The current correction file FILES.COR contains the code necessary to up- date FLB to version l.0A. This includes code to correct for DP LBN's, corrects some DP arithmatic errors, cleans out the high byte in CW2, plus adds a diagnostic capability. In addition, it has been tested on RSX-11M (PLUS) and an RP06 drive. The new diagnostic switch /DA acts the same as the /-LI switch plus it provides a means for the user to force a dif- ferent value into the SIZE value (number of blocks on the device). The default value will be that of the device indi- cated. Otherwise the program will use the supplied value which is stored in DASIZE. For example: FLB TI:=DM:/DA:1:1000/BLK:5:5 The above command string will force the program to set the size parameter to 66048 (decimal). (Arbitrary values must be used with either the /LBN or /BLK switches, because of the syntax. These values must be less than the selected /DA value.) -JBF PAGE 43 FORUTL C SUBROUTINE FLOPEN.FOR C THIS SUBROUTINE READS IN A FILE NAME AFTER PRINTING A C STRING MESSAGE SPECIFIED IN THE CALL, AND PERFORMS AN C ASSIGN TO A LUN ALSO SPECIFIED IN THE CALL. THE STATUS C IS RETURNED WITH IST = 1 INDICATING SUCCESS AND IST = 2 C INDICATING FAILURE VIA EOF ON INPUT C RE-ENTERED 5-MARCH-75 AUTHOR: LARRY SIMPSON C MODIFIED FOR "FOR" COMPILER 15-AUG-75 C --------- C MODIFIED TO CHECK ON EXISTENCE OF A FILE OPENED FOR READ VIA A C DUMMY READ STATEMENT. POSITIVE LUN INDICATES READ, NEGATIVE C INDICATES WRITE. NO CHECK IS PERFORMED FOR WRITE. C FILE NAME AND LENGTH ARE NOW SAVED IN A COMMON AREA C ACCESSIBLE BY THE MAIN PROGRAM. C MODIFIED 29-JAN-76: LARRY SIMPSON ; SUBROUTINE STRCMP ; TO COMPARE TWO STRINGS AND REPORT EQUALITY OR NOT. ; FORTRAN CALL: ; CALL STRCMP(STRING1,STRING2,NCH,IRSLT) ; WHERE STRING1=FIRST STRING (USUALLY ARRAY) ; STRING2=SECOND STRING ; NCH=NUMBER OF CHARACTERS TO COMPARE ; IRSLT=STATUS: 0 -> EQUALITY ; > 0 -> POSITION IN STRINGS AT WHICH = FAILED ; SUBROUTINE MOCNVT ; TO CONVERT MONTHS FROM NUMBER TO ASCII AND VICE VERSA ; FORTRAN CALL: ; CALL MOCNVT(NUM,MONTH,MODE,ISTAT) ; WHERE: ; NUM = NUMBER OF MONTH (1-12) ; MONTH = 3 CHAR ASCII MONTH NAME ; MODE: ; 1 = NUM > ASCII ; 2 = ASCII > NUM ; ISTAT: STATUS RETURN ; 1 = OK ; 2 = INVALID PARAM FOR CONVERSION ; 3 = INVALID MODE .TITLE MOCNVT ; SUBROUTINE STRCON ; STRING CONCATENATION ROUTINE ; TO TAKE A VARIABLE NUMBER OF STRINGS AND CONCATENATE THEM ; INTO ONE STRING. ; FORTRAN CALL: ; CALL STRCON(LENA,LEN,STR,LEN1,STR1[,LEN2,STR2,...]) ; WHERE: ; LENA = ACTUAL LENGTH OF CONCATENATED STRING ; + INDICATES SUCCESSFUL CONCATENATION ; 0 INDICATES ERROR IN CALL ; - INDICATES OVERFLOW, VALUE = LEN ; LEN = MAX. LENGTH OF OUTPUT STRING ; STR = START OF OUTPUT STRING ; LEN1 = LENGTH OF FIRST INPUT STRING ; STR1 = START OF FIRST STRING ; ETC. PAGE 44 FORUTL ; SUBROUTINE AMAXFA.MAC ; SUBROUTINE TO FIND THE MAXIMUM OF A ; SERIES OF REAL*4'S WHOSE STARTING ADDRESS ; AND COUNT ARE GIVEN IN THE CALL. ; FORTRAN CALL: ; CALL AMAXFA(FARR,ICNT,FMAX,IOFF) ; WHERE FARR=STARTING ADDRESS(USUALLY ARRAY NAME) ; ICNT=COUNT OF REALS TO COMPARE(>1) ; IOFF=OFFSET OF MAX VALUE (ARRAY POSITION) ; FMAX=MAX VALUE ; SUBROUTINE CHRCNT ; TO COUNT THE NUMBER OF OCCURRENCES OF A GIVEN ; CHARACTER IN A BUFFER OF SPECIFIED LENGTH ; FORTRAN CALL: ; CALL CHRCNT(NBUF,CBUF,NCHR,CHAR) ; WHERE: ; NBUF=NO. OF CHARACTERS IN BUFFER ; CBUF=START OF CHAR BUFFER ; NCHR=NO. OF SPECIFIED CHAR COUNTED ; CHAR=SPECIFIED CHARACTER (BYTE VAR) ; SUBROUTINE FLINTP.MAC ; FLOATING POINT INTERPOLATION FUNCTION ; IF Y = F(X) AND FOR X1 AND X2 A CORRESPONDING ; Y1 AND Y2 ARE KNOWN, THEN GIVEN X0 BETWEEN ; X1 AND X2, Y0 WILL BE CALCULATED BY ; LINEAR INTERPOLATION. ; FORTRAN CALL: ; Y0 = FLINTP(X1,X2,Y1,Y2,X0) ; ; ; SUBROUTINE LNFILL.MAC ; TO FILL IN BLANKS IN A FORTRAN ARRAY. ; A STARTING ADDRESS, LENGTH AND (OPTIONALLY) A CHARACTER ARE SPECIFIED. ; FORTRAN CALL: ; CALL LNFILL(LEN,ARRAY[,CHAR]) ; WHERE: ; LEN=NO. OF BLANKS TO FILL IN ; ARRAY=NAME OF FIRST POSITION TO FILL ; FIRST BYTE OF CHAR=ASCII CHARACTER TO FILL (DEFAULT=BLANK) .TITLE LNFILL ; SUBROUTINE TRNCAT.MAC ; FORTRAN CALLABLE ROUTINE TO TRUNCATE ; TRAILING BLANKS FROM AN ASCII ARRAY. ; FORTRAN CALL: ; CALL TRNCAT(LIN,NLIN,NONBLK) ; WHERE: ; LIN = START OF ARRAY ; NLIN = NO. OF CHAR IN LINE ; NONBLK = NO. OF CHAR IN LINE AFTER BLANK TRUNCATION PAGE 45 INDEX I D X A Fortran 4-Plus Cross-Reference Program. IDX Will produce a cross reference listing of a F4P program. This cross-reference will list all references to lables, be they varia- bles, routine entries, etc. CALLING SEQUENCE MCR>IDX =/SW/SW Current switches supported are : /DE - Treat debug lines as source /EX - Extend source scan to column 80 /HE - List this message on the terminal /LP - Output in line printer format (132 col.) /NS - Disable listing of FORTRAN source input /F4P - Number lines identically with ; ARITHMETIC STATEMENT <= > ; ASSIGNMENT STATEMENT <* > ; LABEL DEFINITION ; ACCEPT ; ARGUMENT TO SUBPROGRAM ; ASSIGN ; BACKSPACE ; BLOCK DATA ; BYTE ; CALL ; COMMON ; COMMON BLOCK NAME ; CLOSE FILE ; COMPLEX ; DATA STATEMENT ; DECODE ; DEFINE FILE ; DIMENSION ; DO STATEMENT ; DOUBLE PRECISION ; ENDFILE ; ENCODE ; EQUIVALENCE ; EXTERNAL ; ENTRY POINT ; BYTE FUNCTION ; COMPLEX FUNCTION ; DOUBLE PRECISION FUNCTION ; INTEGER FUNCTION ; LOGICAL FUNCTION ; FORMAT STATEMENT ; FIND RECORD ; REAL FUNCTION ; PLAIN FUNCTION ; GO TO STATEMENT ; IF STATEMENT ; INTEGER ; LOGICAL DECL. ; OPEN FILE ; PARAMETER DEF. ; PROGRAM STATEMENT ; PRINT STATEMENT ; ALL READ STATEMENTS ; REAL DECLARATION ; REWIND FILE ; SUBROUTINE ; TYPE STATEMENT ; WRITE STATEMENT PAGE 48 INF INF.DOC INFORM A System Program That Can Display Active Task List Node Usage Clock Queue Device's PUD Partition Map Device Forms Types A Task's ATL A Task's STD A Task's Pending I/O A Terminals Characteristics Frank R. Borger 07-November-1978 PAGE 49 INF INF.DOC PAGE 2 07-Nov-78 ACTIVE TASK LIST ------ ---- ---- FUNCTION -------- Provide a listing of all currently active tasks, along with their address in core. CALLING SEQUENCE ------- -------- MCR>INF ACT ------- ALLOWABLE SWITCH --------- ------ /E Switch provides extended listing, including task STATUS and TI. NODE POOL ACCOUNTING ---- ---- ---------- FUNCTION -------- List detailed accounting of node usage. Includes total number of nodes in the system, number of free nodes, nodes allocated to different tasks and tables. CALLING SEQUENCE ------- -------- MCR>INF NOD ------- ALLOWABLE SWITCHES --------- -------- None. PAGE 50 INF INF.DOC PAGE 3 07-Nov-78 CLOCK QUEUE LIST ----- ----- ---- FUNCTION -------- List all currently scheduled events in the clock queue. CALLING SEQUENCE ------- -------- MCR>INF CKQ ------- ALLOWABLE SWITCHES --------- -------- None. PUD DUMP --- ---- FUNCTION -------- Provide a listing of the PUD for a given device. CALLING SEQUENCE ------- -------- MCR>INF PUD XX:N ------------ Where XX:N is the device descriptor ALLOWABLE SWITCH --------- ------ /F Switch provides full listing of PUD including volumn control block, (not listed by default command.) PAGE 51 INF INF.DOC PAGE 4 07-Nov-78 PARTITION MAP --------- --- FUNCTION -------- Provide a "MAP" of a partition, listing all active tasks (and pure areas,) the FTL, CTL and all COMMON areas. CALLING SEQUENCE ------- -------- MCR>INF MAP XXXXXX -------------- Where XXXXXX= Partition name ALLOWABLE SWITCH --------- ------ /P Switch lists all currently used areas and holes in the parti- tion, ordered sequentially by starting address, providing a much clearer display of why partition XXXXXX is fragmented. FORMS LISTING ----- ------- FUNCTION -------- Provides a listing of all printing devices who have their forms type set to non-zero. CALLING SEQUENCE ------- -------- MCR>INF FRM ------- ALLOWABLE SWITCHES --------- -------- None PAGE 52 INF INF.DOC PAGE 5 07-Nov-78 TASK'S ATL ------ --- FUNCTION -------- Provides a listing of the ATL entry for a specified task. CALLING SEQUENCE ------- -------- MCR>INF ATL XXXXXX -------------- Where XXXXXX is the task to be listed ALLOWABLE SWITCH --------- ------ /TI:TTn Switch list ATL for task at a terminal other than your own. TASK'S STD ------ --- FUNCTION -------- Provides a listing of the STD entry for a specified task. CALLING SEQUENCE ------- -------- MCR>INF STD XXXXXX -------------- Where XXXXXX is the task to be listed ALLOWABLE SWITCH --------- ------ None PAGE 53 INF INF.DOC PAGE 6 07-Nov-78 TASK'S OUTSTANDING IO ------ ----------- -- FUNCTION -------- Provides a listing of the IO request nodes for a specified task. CALLING SEQUENCE ------- -------- MCR>INF IOR XXXXXX -------------- Where XXXXXX is the task to be listed ALLOWABLE SWITCH --------- ------ None TERMINAL DESCRIPTION -------- ----------- FUNCTION -------- List terminal characteristics for a given TTY. CALLING SEQUENCE ------- -------- MCR>INF TER TT:NN ------------- Where TT:NN is the terminal descriptor ALLOWABLE SWITCH --------- ------ None PAGE 54 LIST LIST-11 Version 3.02 LIST-11 LIST-11 is a program for reformatting ASCII files. It can put up to 10 columns of text on a single page. To run LIST-11, the user types: LIS [FILEOUT=FILEIN/SWITCHES] Where the file specifications should be in the form: outdev:outfile.outext=indev:infile.inext/switch:value Switches The number of columns which should be used is specified by the /COlumns switch. Its value is a number from 0 to 10, which indicates the number of desired columns. If the number is 0, as many columns as will fit will be used, up to a maximum of 10. The number of columns is reset to zero after every file is listed and must be specified anew if it should be set otherwise. Paper sizes (LEngth and WIdth) are not changed between listings, so that these need be specified only where they must be different from the default, or on the first listing. All other switches are reset between files. The /TR switch, if present, causes lines which are too wide for the specified number of columns to be truncated. If it is not specified, lines which are too long will be split and all but the first part will be preceded by a "-->". The /NH switch, if present, causes the two line LIST-11 header to be omitted. The /FF switch, if present, causes a form feed in the input file to start a new column in the output file. If the /FF switch is not specified, form feeds in the input file are ignored. The /CT switch, if present, causes a tab to be changed into a space, instead of skipping to the next column. The output page size may be specified by the /WIdth and /LEngth switches, which specify the number of available print co- lumns and lines, respectively. Once a page size has been speci- fied, it is retained until specifically changed by another switch specification. The /PAuse switch will cause output to stop at the end of each page. The output will be restarted when something is typed to the command input dataset. List-11 will prompt for the input by typing the special prompt: PAGE 55 LIST LIST-11 PAGE 2 Version 3.02 LIST PAUSE> after which any input is legal and serves only to end the pause. A control-Z at a pause ends the current listing and will cause LIST-11 to prompt with another "LIS>" for a new set of file spec- ifiers. The /ED switch will cause the top of forms character to be changed from a form feed to a control D. The /RO:n switch causes the output to force each page to be n lines long. This is intended for use with roll paper. In ad- dition, the form feeds are replaced by a line of "=" to delimit the pages. Both the switch and n must be specified for each file. The /UC switch causes lower case letters to be translated to the corresponding upper case characters. This is helpful when listing on a device not containing the full 96-character ASCII character set. The /NP switch causes pagination to be suppressed; that is, no headers are produced and no formfeeds or other page dividers are inserted in the file. This mode may be used (possibly in con- junction with the /RL:nnn switch) to produce a file of known max- imum line width. Example: MCR>LIS LIS>LP:=PROG.SRC/TR/CO:3 MCR>LIS LP:=MANUAL.DOC/NH/FF/CO:2 The first file, DK:PROG.SRC, is printed on the line printer, in a 3 columns per page format. The file MANUAL.DOC is then printed without a header and each "page" beginning at the top of the next column. This is useful for listing RUNOFF output files in a two columns per page format. PAGE 56 LUT LUT A task to list the Logical Unit Table of a task LUT can be used to display information as to any files currently opened by a given task. Information listed includes: DEVICE, UIC AND FILE SPECIFICATION ACCESS COUNT, # OF RETRIEVAL POINTERS AND WINDOW SIZE FIRST BLOCK NUMBER AND TOTAL NUMBER OF BLOCKS Calling sequence: MCR>LUT XXXXXX/TI:TTN Where XXXXXX=Task Name and TTN is the TI for the task PAGE 57 MASSAGE NEW SYSTEM COMMANDS A series of commands have been added to our system to make life easier for users of the computer. These commands are designed to make life easier by giving easier syntax for often used commands. Note that optional parts of the commands are shown in "[]"'s. BRI[ef] [NAME.TYP;VERS] Produces brief directory of files *1 BLO[cks] [NAME.TYP;VERS] Reports blocks used/allocated *1 COP[y] [DVn:{N,M}]NAME.TYP Copies a file from another disk or UIC *1 DIR[ectory] [NAME.TYP;VERS] Produces directory of files *1 DOC[ument] NAME.TYP[;VERS] Prints specified file at LP1: (forms 1) FOR[tran] NAME Compile Fortran source with F77 Compiler *5 FRE[e] DVN: list free blocks on specified device MAX NAME.TYP[;VERS] Compile Macro source with MAC compiler *5 PRI[nt] NAME.TYP[;VERS] Prints specified file at LP0: PRO[tect] NAME.TYPE[;VERS] Prevent file from being deleted PUR[ge] NAME.TYP Purges named file[s] to 1 copy *1 REC[over] [NAME.TYPE;VER] REcovers locked file(s) *1 SUB[mit] NAME[.TYP;VERS] Submit file to batch *4 TYP[e] NAME.TYP[;VERS] List named file at terminal UNP[rotect] NAME.TYPE[;VERS] Reset effect of protecting file USE N,M Sets your working UIC to N,M 1. If no file named, defaults to "*.*;*" If file name only given, defaults to "NAME.*;*" 2. Wild card ("*") use usually unrestricted 3. Care should be taken using wild cards with "PURge" and "FREe" 4. Defaults to NAME.BIS 5. XXX NAME defaults to "F77 NAME,NAME/-SP=NAME.FOR" or "MAC NAME,NAME/-SP=NAME.MAC" A provision for easily adding MCR programs to the system has also been introduced. A command of the form "XYZ ....." When "...XYZ" is not in- stalled in the system will have the following result. 1 Attempt to INStall LB:[11,1]XXX.TSX 2 If successful execute said MCR task 3 remove task "...XXX" when it finished If the install fails, you will get a "TASK NOT INSTALLED" error PAGE 58 ORC OBJECT TO MACRO CONVERSION (ORC) 1. INTRODUCTION ORC is a utility which converts PDP-11 object code to MACRO-11. Its uses include: * checking code produced by compilers * on-line debugging of code produced by a compiler which does not give an assembly listing (eg. CORAL). For ORC to produce sensible output, the object code should have data and instructions in separate program sections with D and I attributes respectively. The object code produced by the CORAL and F4P compilers satisfy this requirement. The F4P compiler produces its branch instructions after it has produced the other object code which may look a little strange, but is in fact correct MACRO-11 code. The threaded code produced by the FORTRAN compiler (FOR) is not suitable for conversion to MACRO-11. The MACRO-11 code produced by ORC can be assembled in the usual way to produce an assembly listing. 2. USING ORC When the task is initiated it issues a prompt and receives a command line of the form: ORC>outputfilespec=inputfilespec The usual RSX-11 conventions for file specifications apply. No switches are allowed in the command line. If the extension is not supplied in a file specification, it is assumed to be: .OBJ for the input file .MAC for the output file An indirect command file may be specified, but indirect command files may not be nested. ORC converts the object code in the input file into MACRO-11 and writes it to the output file. The MACRO-11 file can then be assembled in the usual way to produce an assembly listing. During processing, ORC allocates a temporary file (ORC.TMP) under the user's uic on the system device. If ORC is aborted, this file should be deleted. ORC uses in-core tables to store local symbols, labels, global -1- PAGE 59 ORC OBJECT TO MACRO CONVERSION (ORC) symbols, and program section names. These can hold up to: * 256 local symbols * 512 local labels * 100 global symbol definitions * 26 program section names This should be enough for most object files, but the first three of these tables can be extended at task build time, if required. Local labels are used when referring to locations within the same (instruction) program section. They are of the form n$ where n is the location of the label. Example: MOV R0,R1 BEQ 6$ CLR (R0) 6$: INC R1 Local symbols are used when referring to locations within other program sections, or within the same program section if it contains data. They are of the form xn, where x is a letter (A, B, C,...) defining the program section and n is the location of the symbol within the program section. Example: .PSECT DATA,D C00000: .WORD 0 C00002: .WORD C00000 ; .PSECT INSTR,I MOV #C00002,R0 In certain circumstances, ORC may reference symbols which are not defined. The positions of these symbols can be determined from their names. 3. ERROR MESSAGES ORC -- COMMAND I/O ERROR An I/O error ocurred during input of the command line, or a bad indirect command file name was specified, or indirect command files were nested. ORC -- SYNTAX ERROR A syntax error was detected in the input line. ORC -- BAD INPUT FILE SPEC ORC -- BAD OUTPUT FILE SPEC A switch was specified or 'wildcards' were used in the file specification. -2- PAGE 60 ORC OBJECT TO MACRO CONVERSION (ORC) ORC -- OPEN FAILURE ON xxxxxx FILE ORC -- I/O ERROR ON xxxxxx FILE ORC -- FAILED TO CLOSE xxxxxx FILE These errors may be caused for a variety of reasons, eg. device offline, device full, privilege violation, file does not exist. The message specifies whether the error ocurred on the INPUT, OUTPUT or SCRATCH file. ORC -- PSECT TABLE OVERFLOW Only 26. program sections are allowed in one object file, including the absolute (. ABS.) and blank PSECTs. ORC -- LABEL TABLE OVERFLOW Only 512. local labels are allowed in one object file. This number can be increased by editing the command file and rebuilding ORC. ORC -- LOCAL SYMBOL TABLE OVERFLOW Only 256. local symbols are allowed in one object file. This number can be increased by editing the command file and rebuilding ORC. ORC -- GLOBAL SYMBOL TABLE OVERFLOW Only 100. global symbol definitions are allowed in one object file. This number can be increased by editing the command file and rebuilding ORC. PAGE 61 PAG NEW UTILITY PROGRAM AVAILABLE PAG PAGinate listing program Provides listings of programs etc on a paginated basis so printing does not occur near the paper folds. Also, listing will contain 2 header lines identfying Our institution. DEVice, UIC, file name, extension and version # DATE and TIME of listing calling sequence MCR>PAG[elist] DEV:[UIC]NAME.TYP;VERS or MCR>PAG DEV:[UIC]NAME.TYP=DEV:[UIC]NAME.TYP If only one file specification is entered, the listing will be queued for printing at LP: If both input and output file specifications are entered, the listing file will be left on the disk and not spooled. One switch has been provided to enhance listings at LP1: The switch "/TA" instructs PAG to output the listing with leading "TAB" characters so that the output on LP1, after removing the margins, can be punched and inserted into a ring binder without losing the first few characters of in- formation. PAGE 62 PLOTSUBS PLOTSUBS fortran callable subroutine package ------- -------- ---------- ------- for storage scope plotting --- ------- ----- -------- PLOTSUBS is a set of object modules of fortran subrou- tines suitable for the plotting of graphic data, (axes, data points, contiguous curves,anotations) on the VT-01 storage scope. PLOTSUBS may be included in any fortran program during task build proceedures. the following is a typical procee- dure. TKB>XXXXXX,XXXXXX=XXXXXX,PLOTSUBS/CC,PLOTDATA TKB>/ ENTER OPTIONS TKB>ASG=VC:N (N=DEV USED IN SUBROUTINE CALLS) Descriptions of the various subroutines and their cal- ling proceedures follows. Unless otherwise mentioned, all plot co-ordinates refer to a 4096 X 4096 matrix with 0,0 at the lower left corner of the screen and 2048,2048 at the center of the screen. PAGE 63 PLOTSUBS PAGE 2 CALL OPEN(IDEV) Prepares storage scope (assigned to device idev during later task build proceedure for plotting.) Scope is programmed for storage mode, non write-thru, and put through an erase cycle. A 1-second wait is introduced to insure that erasure is finished before plotting starts. PAGE 64 PLOTSUBS PAGE 3 CALL CHARAC(IDEV,IMESS,NBYTE,IXP,IYP,ISIZE,IORIEN) VARIABLE DESCRIPTION IDEV =The fortran logical device number IMESS =A (usually dimensioned) variable containing an ascii message as an ascii byte string. NBYTE =The number of characters in the message IXP =X location of start of message, defined at lower left corner of character. IYP =Y location of start of message, also lower left ISIZE =Size of characters, (7 to 20 is normal size) IORIEN =Character orientation. 0=letters on right side, 1= characters upright, 2=characters on left side. PAGE 65 PLOTSUBS PAGE 4 CALL DATA(IDEV,INCREM,NWORDS,IXP,IYP,IMODE) VARIABLE DESCRIPTION IDEV =The fortran device number INCREM=A dimensioned variable containing word/byte values equal to the X and Y increments from a data point to the next point in the curve. NWORDS=The number of increment pairs in INCREM IXP =X location of first point IYP =Y location of first point IMODE =Mode of incremental data. 0=byte,1=word PAGE 66 PLOTSUBS PAGE 5 CALL CODATA(IDEV,ICOORD,NPOINT,IXP,IYP) VARIABLE DESCRIPTION IDEV =The Fortran device number ICOORD=A dimensioned variable containing successive X and Y co-ordinates of points to be plotted NPOINT=The number of points to be plotted IXP =X location of initial point IYP =Y location of initial point PAGE 67 PLOTSUBS PAGE 6 CALL AXIS(IDEV,IXP,IYP,LENGTH,JDIR,ILAB,NCHAR) VARIABLE DEFINITION IDEV =Fortran logical device number IXP =X location of axis start IYP =Y location of axis start LENGTH=Length of axis (must be a multiple of 100) JDIR =Direction code, 0=X-axis,1=Y ILABEL=Dimensioned variable containing axis label as an ascii string NCHAR =Number of characters in the lable. if NCHAR =0, no lable will be printed. PAGE 68 PLOTSUBS PAGE 7 CALL SYMBOL(IDEV,IXP,IYP,ICHAR) VARIABLE DESCRIPTION IDEV =Fortran logical device number IXP =X location of symbol center IYP =Y location of symbol center NCHAR =Symbol code 1=PLUS 2=CROSS 3=DIAMOND 4=SQUARE 5=CIRCLE PAGE 69 QUX QUX - Queue listing with extensions 5-SEP-79 ...QUX, for QUeue Extended, reports on entries in the spool queues. It has options which enable it to list expected print time and pages and also give expanded listings of the files contained in concatenated output. command format - MCR>QUX [/switches] Note that QUX with no switches is equivalent to queue/all. the available switches are as follows - /TI[:filespec] - List the print time and pages for files queued for printing. if it is a concatenated entry, all the files in that entry are summed up and the totals printed. If /TI:filespec is used, print time and pages are reported for that file alone and the queue is not searched. this is useful to examine an output file for print time before it is queued for printing. /EC - Expand concatenated entries. Individual entries in a concatenated list will be listed. /OW - List only those files associated with the current users default UIC. This is equivalent to QUE/LI. /PD - Print deferred. This switch will list the files in the 'print deferred' queue. These files are ones which are not yet queued for printing, but are future concatenated entries. Also lists the files being generated by active batch jobs, i.e. BATCH.LOG and LP.SPR files. Entries in the active and pending queues will not be listed with /PD. ** notes ** Accumulated times are printed for each queue if /TI is specified. These times are based on LP0: being 300LPM and any TT device (TT01 or TT03) being set at 2400 baud. For LA36's at 600 baud, multiply print time by 4. for LP1: at 150 lines/minute, multiply print time by 2. If there is an error opening a file, the FCS error code is printed in the page count column. This will be a negative number. Maximum field for file version number is 4 octal characters. Maximum field for sequence is 3 decimal characters. PAGE 70 QUX ...QUX - examples 5-SEP-79 MCR>QUX /TI DEV ACT ACCOUNT FILE SPECIFICATION SEQ PRI FO CO PBC PAGES MINS BA0 * [200,201] DB0:[1,4]RAD2.BIS;4 50 0 0 BA0 * [330,2] DB2:[330,2]SUMMER3.CMD;2 100 0 1 * LP0 * [310,1] DB2:[310,1]SFSIN.FTN;3 100 0 1 *N 5 0.9 TT10 * [310,1] DB2:[310,1]PFSCM.COM;24 100 0 1 * 3 0.5 LP0 [310,1] DB2:[310,1]PFSCM.COM;24 1 100 0 1 * 3 0.5 -------------------------------------------------------------------------------- LP0 8 1.4 TT10 @2400 BAUD 3 0.5 MCR>QUX /EC DEV ACT ACCOUNT FILE SPECIFICATION SEQ PRI FO CO PBC BA0 * [200,201] DB0:[1,4]RAD2.BIS;4 50 0 0 BA0 * [330,2] DB2:[330,2]SUMMER3.CMD;2 100 0 1 * LP0 * [225,22] DB0:[1,4]XBSUSE.LST;1 100 0 1 LP0 [230,10] DB1:[230,10]DRS.SPR;1 1 100 0 1 LP0 [310,1] TT1:CONCATENATED 2 100 0 0 C [310,1] DB2:[310,1]PFSCM.COM;24 100 0 1 * C [310,1] DB2:[310,1]PFSLI.FTN;32 100 0 1 * C MCR> QUX/OW/EC DEV ACT ACCOUNT FILE SPECIFICATION SEQ PRI FO CO PBC LP0 [310,1] TT1:CONCATENATED 2 100 0 0 C [310,1] DB2:[310,1]PFSCM.COM;24 100 0 1 * C [310,1] DB2:[310,1]PFSLI.FTN;32 100 0 1 * C MCR> QUX/TI/PD DEV ACT ACCOUNT FILE SPECIFICATION SEQ PRI FO CO PBC PAGES MINS LP0 D [1,1] BA0:CONCATENATED 100 0 1 C D [1,1] DB0:[1,4]BATCH.LOG;4 100 0 1 C -29 0.0 D [325,3] DB0:[1,4]LP.SPR;1 100 0 1 C 17 3.5 LP0 D [1,1] BA1:CONCATENATED 50 0 0 C D [1,1] DB0:[1,4]BATCH.LOG;5 50 0 1 C -29 0.0 -------------------------------------------------------------------------------- LP0 17 3.5 MCR> QUX/TI:DB1:[225,1]IRACP.MAP FILE SPECIFICATION LINES PAGES MINS @300 LPM MINS @2400 BAUD DB1:[225,1]IRACP.MAP 4094 63 13.6 13.8 PAGE 71 RCV new system utility RCV MCR task to recover a file locked as a result of task abortion Original author R B French NOV 76 The Boeing Co /L switch added F. Borger MAR 77 Michael Reese /A switch, large file modifications, FEB 81 calling sequence MCR>RCV Filename[/SWitch] The normal REC[over] command will only unlock a file that was locked due to abnornal termination. After use, some files may end up 0 length due to the end of file indicators not being properly reset. RCV will unlock the file (if locked,) unless another task has write ac- cess. It will then scan the file and rewrite file attributes to reflect the actual size of the file (rather than 0). RCV has two legal switches: /LA:NNN Set number of records to be NNN /AD:NNN Change number of records by NNN (+/-) NNN must be a legal single-precision decimal number (between -32767 and 32767) For fixed length record files, this switch lets one override the result of the recovery and explicitly determine the number of records. The previous limitation involving large files and file header extensions has been removed. PAGE 72 RNP RNP is a pre-proccessor for runoff files which allows for the in- teractive entry of variable data into the body of standard forms (letters, reports, etc.) for later processing by RNO. TYPICAL COMMAND LINE MCR>RNP DDN:FILE.EXT=DDN:FILE.EXT Input defaults to: SY0:DOC.RNP Output defaults to: SY0:RNORNP.RNO EXAMPLES: MCR>RNP PROGRAM This command line causes RNP to become active, and to begin read- ing from the file SY0:RNP.RNP. RNP will then create a file SY:PROGRAM.RNO under the current UIC, and write the documentation produced to this output file. MCR>RNP This command causes RNP to become active and await command input. MCR>RNP LETTER=LETTER This command causes RNP to become active, use the file SY:LETTER.RNP as input, and create the file SY:LETTER.RNO. FEATURES: The RNP utility reads lines from the specified input file and directly writes these lines to the output file, with the exception of those lines which begin with a control character. The control character indicates to RNP that a special function is to be performed at that point of the procedure. The following control characters (and associated actions) are currently recog- nized by RNP: PAGE 73 RNP CHAR FUNCTION # Mark this position in output. ? Accept input from the terminal, until an EOF (CONTROL-Z) is typed if immediate EOF is encountered, rewind file to last marked position. " Output record to the terminal, not to the output file, (used as a prompt) @ Resume input from the specified file (four levels of indirection are allowed). SAMPLE OF RNP OPERATION *****************MAIN COMMAND FILE "DOC.SAM" "SAMPLE TERMINAL PROMPT ?THIS IS NOT SEEN IN OUTPUT, BUT TURNS ON TERMINAL INPUT END OF TERMINAL INPUT NOW READ FROM DOC.SA1 @DOC.SA1 END OF DOC.SA1 INPUT END OF FILE DOC.SAM *****************FIRST SECONDARY FILE "DOC.SA1" ****************************** THIS IS THE INPUT FROM DOC.SA1 ****************************** @DOC.SA2 *****************SECOND SECONDARY FILE "DOC.SA2" ============================== THIS IS THE INPUT FROM DOC.SA2 ============================== *****************RESULTANT OUTPUT THIS WAS TYPED IN IN RESPONSE TO THE TERMINAL PROMPT END OF TERMINAL INPUT NOW READ FROM DOC.SA1 ****************************** THIS IS THE INPUT FROM DOC.SA1 ****************************** ============================== THIS IS THE INPUT FROM DOC.SA2 ============================== END OF DOC.SA1 INPUT END OF FILE DOC.SAM PAGE 74 SPELL SPELL 1.0 Summary SPELL is a system of checking for spelling errors in text files on the RSX-11M operating system. The program SPELL does the checking and optionally may make changes, while DICTMK for- mats a file for SPELL to use. It is written in FORTRAN-77 except for certain file access routines that are written in Macro. The program has been optimized as much as possible for speed. In non-interactive mode a file will be produced which contains all the words from the document that SPELL could not find in its dic- tionary. In interactive mode words can be replaced, added to the dictionary (DICTMK will need to be run again), or simply ignored. For an in-depth see the source code as it contains much com- ments. Automated extractions of comments (C+/C-) will tell the workings of all the routines. 2.0 Background The programs were written in FORTRAN-77 and were developed on a PDP-11/t55 with 6-RK05, running RSX-11M V3.2. The programs came from a desire on my part to have a system that could be used to check my submissions for the DECUS North Texas Local Users Group Newsletter. The only spelling checker I could find was the one included in the Software Tools section of the Spring 81 RSXSIG tape. As I didn't want to build software tools, I used the data base as a starting point for program development. As sequential reads were too slow for the upwards of 42,000 words in the data base, I used Marge Knox's (now FORTRAN-77). Random ac- cess - block i/o was decided on to minimize the time for disk i/o. Using Ralph Stammerjohn's Index to the past RSXSIG tapes, I was able to come up with Phil Cannon's routines for FCS file ac- cess to the FDB. This enabled me to build the dictionary (using DICTMK) using random access block i/o, set the size of the file, and to truncate to the last block used on exit. The prototype of this program would read the document to be checked and put each different word in a list to be checked by the dictionary and those misspelled written out to a file. This worked somewhat allright for small files, but the larger the file the more time that was spent checking against the list for each word to insure the word was not already included. Even small files yielded 500 different words to be checked. This was before the index for each letter was included on the average of 30 reads for each word. PAGE 75 SPELL Spelling Checker PAGE 2 3.0 Use To build SPELL copy DICT.SEQ to uic [3,3] or any UIC you want if changes are made to the source code. @DICTMK will pro- duce the DICTMK.TSK and @SPELL will produce the SPELL.TSK. Run DICTMK to produce DICT.RAF (the random access file). Install SPELL or set up CCL to do it and pass command lines. To check a document for spelling, >SPE filename[/sw] will do it. If you are not using a VT52 type terminal, please make changes to SUBROUTINE DISPLA for the right escape sequences for clear screen. 4.0 DICTMK DICTMK is the dictionary maker for the spelling system. It is used to provide a random access block i/o dictionary with internal indexes for all the letters. Access to the File Des- criptor Block is possible by the use of Phil Cannon's routines that use an internal FDB in a byte array. Thus truncate on close is possible using block i/o. DICTMK will also provide statistics on the words in the dictionary after it has built the dictionary. 4.1 Dictionary The dictionary that goes along with this program comes from the software tools section of the Spring 81 RSXSIG tape. It was DICT.;1. It contains more than 42,000 words. The shortest word is 'a' and the longest is 22 letters. From looking through it, there are some proper names and places. This may or may not be advantageous 3% of the total space, so deleting them may not buy you much space. 4.2 Adding words When spell runs and produces a list of words that you want to add to the dictionary, run DICTMK from where SPELL ran (that's where the file of words is. DICTMK will take the file and merge it into DICT.SEQ then produce another DICT.RAF. PAGE 76 SPELL Spelling Checker PAGE 3 5.0 SPELL SPELL is the spelling checker program. It uses the diction- ary file and its own internal list, and checks the text for words not found in either. Several switches are available for the com- mand line, and several commands are available in the interactive mode. 5.1 Switches When invoking SPELL several switches are available. To in- voke SPELL: >SPE filename[switches] or >SPE SPE>filename[switches] The switches for the command line are as follows: /Q process in quick mode (non interactive) /F file is FORTRAN source, process comments only /T terse comments, on interactive, display line and word only /N numbers are valid symbols in tokens /L[:filename] preload the add list with words that are correct if filename exists use this list, if not use 'SPELL.DCT' /S:x ignore words with 'x' or less letters 5.2 Modes There are two modes of operation for the spelling checker. Depending on the availability mode can be chosen. The interac- tive is the non-quick mode, so named since it takes longer to process a document in this mode. 5.2.1 Quick - The quick mode provides for no interactive processing. It will scan the document and make a list of words that it didn't find in its dictionary or in its internal list. This is the mode used for long documents and on line checking. PAGE 77 SPELL Spelling Checker PAGE 4 5.2.2 Non-quick - The non-quick mode (default) is interactive with the termi- nal and uses screen clearing. This screen clearing can be ad- justed to be compatible with the terminal type. For adjustments see SUBROUTINE DISPLA. In this mode the document is scanned for number of lines, to provide the operator with a scale of how far he has to go. If the verbose command has been used (default), the full display line and the given word is displayed. 5.2.2.1 Display - The terminal display in the verbose mode will display the spelling header line which holds the title and version number. Next is a short display of the commands available. Then a short list of the statistics of the spelling checker so far this ses- sion. Thus the operator can see how many lines have been pro- cessed, how many words, and the number of words added to each of the lists. Next is the line containing the word in question and then the word itself with a prompt. 5.2.2.2 Commands - The commands available (where is a number between 1-9) ignore words or less in length A this word is correct, add to dictionary C this word is correct, do not add to dictionary E exchange words, but do not add to list L replace current line N next word, do not add to list T terse display V verbose display W wrong spelling, make correction to dictionary X exit, as if end of document was here 5.3 Adjustments Several adjustments can be made to this program by the in- terested user. Words can be added to the internal list (at the sacrifice of space). Overlays are possible. Adjustments to the display section are possible for other than VT52 type terminals. The location of the dictionary can modified to increase the speed of reads. PAGE 78 SPELL Spelling Checker PAGE 5 5.3.1 Overlay - Two overlay descriptions are given if you need them. SPEED.ODL has been set up to provide the fastest running of the overlay. The most used portions are all in memory so no overlay reads are needed. SPACE.ODL has been set up to provide the smal- lest version of SPELL. Only those sections needed are in memory at one time. It will probably be very slow since many overlay reads are needed for each and every word checked. These overlays are not tested so don't blame me if they don't work. SPEED.ODL will not run faster than the non-overlayed SPELL. SPELL will run faster if adjustments are made to FNDNOR which fills the normally used words list. If more words are included internally a incre- ase in speed will be likely but this takes space and this task is at the limit now. 5.3.2 Add words - There is a little space left in the program to allow for the expansion of the internal list it checks first. The current words in this list were found in the "Book of lists" which refer- ences "American Heritage Word Frequency Book" of 1971. There are currently 12 words in this list in the order in which they occur in their usage. If it can be found a longer and more complete list is in "Computational Analysis of Present-Day American En- glish" by H. Kucera, Brown University Press, 1967. From this it can be seen that with a list of 16 words 28 per cent of the words in a document can be found. If 64 words are used 43 percent can be found with a corresponding decrease English occur in a vocabu- lary of 134 words. 5.3.3 Display - Adjustments can be made to SUBROUTINE DISPLA to provide the escape sequences for ANSI VT100 and others. Even fancier termi- nal i/o can be done. 5.3.4 Disk - A great increase in speed can be made if the dictionary is kept on a solid state disk. PAGE 79 SPY Aeronautical Research Associates of Princeton (A.R.A.P.) Box 2229, Princeton, NJ 08540 (609) 452-2950 Author: J.D. Leonard SPY is an interactive display program written in the spirit of DEMO and similar to the display's available on the VAX. SPY will dy- namically display timesharing task activity on an IAS system. It was developed on IAS VS3.0, so some changes may need to be made for IAS VS2.0. SPY will run on terminals which support direct cursor ad- dressing. Refer to SPYBLD.DOC and SPYIN.FTN to build SPY for various terminal types. The default is VT52. SPY uses about 5700 words for a 32 terminal 8 batch stream system and about 5200 words for a 16 terminal 4 batch stream system. CPU requirements are on the order of DEMO for similar update intervals. SPY will display itself while running so you can see how much of the system it is using. SPY currently offers a choice of 2 displays. Future versions will hopefully display information on disk activity. Display #1 shows the percent of CPU time spent in Batch, Inter- active or terminals, Swap time, Null time, and Real time or System time. Percent, # of ticks accumulated over last interval, and bar graphs showing the percentages are updated at the specified interval. The percentages are the same as those displayed in the new DECUS DEMO program. Display #2 shows timesharing job activity on a per-terminal basis. Each line shows the TI, username, jobs running (up to 3), to- tal ticks accumulated for the job(s), ticks used since last display update, percent utilization of elaplsed time, and a bar graph of the percentage used. Up to 70% is shown on the graph. The display is updated at the specified interval, a'la DEMO. The command line to initiate ...SPY is as follows - MCR> SPY[display #] [terminal type] where - display # is either 1 or 2. If not supplied the default display (task build parm) will be run. terminal type is a 4 character mneumonic to describe the type of terminal SPY will be running on. This is to set the proper escape sequences if they differ from the de- fault. See SPYIN.FTN to define terminal types other than the SORO(C). e.g. MCR> SPY1 MCR> SPY VT52 MCR> SPY2 SORO PAGE 80 SPY SPY.DOC PAGE 2 SPY VS02.0 10/23/79 The following commands are available while SPY is running. Input is processed as it is in DEMO. Dn where n = 1 changes to display 1 and n = 2 changes to display 2 In where n is the time between display updates in seconds, like DEMO. C Clear screen and refresh display. X or ^Z Cause SPY to exit. The following command descriptions pertain only to display number 2. Ln where n is the number of lines to display, normally 24. e.g. may set to 14 if on VT100 in 132 col mode. The value of L is shown at the bottom of display 2 (L=n). R range1,range2, ....rangen Set the range of terminals to display where range1 through rangen can be any one of the following - DEF - set range to default setting specified at task build time. ALL - set range for all possible terminals to display. Will set to display MAXTT terminals and MAXBA batch stre- ams. See SPYBLD.DOC and SPY.CMD. TTn or BAn - for a single terminal where n is the octal un- it number. TTn-m or BAn-m - for an inclusive range of terminals where n,m are the octal unit numbers. m must be .GE. to n. Any combination of the above is valid, presuming the unit numbers are within the upper limits set by MAXTT and MAXBA. e.g. R TT1-6,BA0-2,TT15,TT20 R ALL R DEF,BA5 PAGE 81 SPY SPY.DOC PAGE 3 SPY VS02.0 10/23/79 ** Notes on display 2 ** If the selected range encompasses more terminals than there is room to display them, SPY will - 1) Try to display terminals with only users logged on, if this exceeds the display area then - 2) SPY will select those logged on with jobs running or suspended. If this number is less than the display area, some terminals on- ly logged on will also be shown, to fill out the display. If the number of terminals with jobs running is greater than the display area then - 3) SPY will select the jobs with the largest percent useage and display only those jobs. Setting L to a small number will force this deduction to take place. Also shown on display 2 is 'SF', the swap flag indicator. If this is '*' then one of the jobs running from that terminal was swapped out when SPY 'looked' at it. Time of day and ticks elapsed since last update are displayed on the top line. On the bottom line is the sum of all timesharing jobs CPU useage divided by elapsed time to give percent utilization. UNS is the number of users (logged on) not shown if they exceed the number of lines to display, and JNS which is jobs not shown if there are some of those not displayed. PAGE 82 SRD SRD - Sorted Directory Utility ============================== User's Guide ============ 1. Introduction ============ SRD is a utility that produces sorted directory listings and performs some useful directory manipulation that is (still) absent from PIP. In addition it produces an out- put file that can be edited by the standard RSX Editor (EDI) [which PIP does not] and provides a wildcard facil- ity in specifying filenames superior to PIP so that, for instance, all files beginning with the letters RSX could be listed. SRD has to read the entire directory into core before sorting it. The size of it's buffer can be increased by installing it with an increment. On an 11M system, it will try expand itself dynamically. If it cannot fit the entire directory in core, it will give a warning message and do the directory in chunks. Each chunk will be sorted seperately, however. A write-back will be cancelled in this case. 2. Command Line. ============= SRD can be invoked by any of the standard RSX/IAS invocation methods, i.e. RUN ...SRD or SRD or SRD command-line In either of the first two cases, SRD prompts for further commands with: SRD> A CTRL-Z will terminate SRD in this mode. The format of the command line is similar to PIP's directory operations, i.e. SRD>[output filespec=][input filespec][switches] where Output Filespec defines the output specification for the listing. This may be a file (e.g. DIR.LST), a device (e.g. LP:) or omitted all together (in which case TI: is used). If an output specification is given at all it defaults to SY:DIRECTORY.LST. PAGE 83 SRD Input Filespec defines the input specification defining the files on which the switches are to act. This usually works (see the switch /WI for a further explanation) on a 'partial specification' basis for each of the filename, extension and version number fields so that: SRD SU/LI not only lists out the latest file called SU (as PIP would), but lists out all files whose filename starts with the two letters SU, for all extensions and all versions. To emphasise this, note that S.M;1/LI would list out all the following:- S.M;1 SYSTEM.MAC;1 SYS.MAP;1 START.MY;13 and so on. Naturally, if the Input Filespec is omitted, *.*;* is assumed. Switches are any valid combination of the switches described in the next section. Defaults for the various switches will be discussed later. Note that SRD will accept an Indirect Command File as input. PAGE 84 SRD 3. Switches ======== 1. Produce a Directory Listing (/LI:n) This just lists the filename, extension and version of the files that meet the specification given. The output is sorted, by default, into the order:- Ascending on File Extension Ascending on File Name then Ascending on File Extension then Descending on File Version In addition a header and trailer line are output for each UFD. The header line contains the name of the UFD, the current date and time, and the command line that was originally used. the trailer line contains the number of files selected, and the total number of files in the directory. If one of the switches /MI, /FU, /AE, /AF, /BE, /BF or /DA is specified the total number of blocks used/allocated (for those files selected) is also listed. This switch can be negated and used to suppress the listing that usually accompanies some of the other switches (e.g. /WB or /PU) - in which case just the header and trailer lines are printed. If n is specified, it defines the width of the listing (72 to 132) - if not it defaults to the device buffer size. 2. Produce a 'Middle' Directory Listing (/MI:n, /M2) This acts similarly to the /LI switch, except that it lists out more information. The extra information listed out depends on the setting of the /M2 switch and is either (/M2 not specified):- Creation Date and Time Revision Date and Time Revision Number or (/M2 specified):- Number of Blocks Allocated to File End of File Block Number Contiguous/Locked/Multiheader Flags File ID Creation Date and Time (Revision Date if /RD specified) PAGE 85 SRD 3. Produce a Full Directory Listing (/FU:n) This acts similarly to the /LI switch, except that it lists out yet more information, i.e. Number of Blocks allocated to File End of File Block Number Contiguous/Locked/Multiheader Flags File ID Owner UIC Protection Codes Creation Date and Time Revision Date and Time Revision Number Note that while a file is being created SRD will list the blocks allocated as 0, rather than the value PIP produces, because the header is not yet set up properly. n, if specified, has the same meaning as in /LI. 4. Change the Sort Order (/NA) If this switch is specified the output sort order is altered to be:- Ascending on File Name then Ascending on File Extension then Descending on File Version 5. Select Files not Specified (/NE) If this switch is specified then all files that do not meet the given specification are listed out. 6. Select Files by Version Number (/HV:n) This switch lists out all files which meet the given specification whose version number is greater than or equal to n. If not specified, n defaults to 2. 7. Select Most Recent Versions of Files (/SV:n) This switch lists out the latest n versions of all files that meet the given specification. If not given, n defaults to 1. If n is -1 then this lists out the oldest version of the file. 8. Select Obsolete Versions of Files (/OV:n) This switch restricts the listing of file names to all versions except the "n" highest versions. The default value for "n" is 1. For a given "n", /OV:n lists file names not listed by /SV:n, and the files listed are those that would be deleted if /PU:n were specified. As indicated by the definition, if n is -1 then all but the oldest version are listed out. PAGE 86 SRD 9. Select Files by Date (/AE,/AF,/BE,/BF,/DA) Each of these switches takes an optional date and/or time as parameter, in the form dd-mmm-yy hh:mm, or hh:mm dd-mmm-yy, etc. e.g.: /DA: 03-DEC-79 10:30 (In fact the date may be specified as ddmmmyy if desired). If no date is specified, today's date is assumed. If no time is specified, time checks are ignored. Then /AE lists all files created on or after the given date (and time). /AF lists all files created after (but not on) the given date (and time). /BE lists all files created on or before the given date (and time). /BF lists all files created before (but not on) the given date (and time). /DA lists all files created on the given date (and time). For these switches the listing includes the creation date and time. If the /RD switch is specified then the Revision Date is used for the checks and the listing includes the Revision Date and Time. 10. Use wildcards in filename (/SE:filespec) Because of the parsing structure in RSX, it is impossible to have wildcards for letters in the Input Filespec, and so this switch is included to allow the facility. The filespec argument it takes is identical to that defining the Input Filespec with the following additional features:- (i) % (or ?) matches one wildcard character. (ii) * matches any number (including zero) of wildcard characters. Any combination of these characters may be used in any of the filename, extension or version number fields. Note that within each field, if an * is specified somewhere, and the final character is not an * then that final character is assumed to be required as the last character of the field. (e.g. *D will match FRED but not FREDA *D* will match either). PAGE 87 SRD Example: Suppose we have the files:- FRED, FREDA, FREDERIK, FEED, FILD, FEEDER, FRIED, FD then /SE:F%%D will match FRED, FREDA, FREDERIK, FEED, FILD,FEEDER (if /WI specified) /SE:F%%D< will match FRED, FEED, FILD (if /WI not specified) /SE:F*D will match FRED, FEED, FILD, FRIED, FD /SE:F*D* will match everything. (Note that /SE cannot be used in combination with a standard Input Filespec). 11. Delete Files (/DE) This switch deletes (and lists) all files that meet the given specification. 12. Purge the directory (/PU:n) This switches purges all but the highest n versions of all files meeting the Input File Specification and lists those purged. If not specified, n defaults to 1. If n is -1 then all but the oldest version of the specified files are purged. 13. Selectively Delete Files (/SD:filespec) This switch lists all the files that meet the given specification, and for each one prompts the user to see if he wants to delete it. There are five allowable replies:- Y = Delete this file N = Do Not Delete This File G = Delete the rest of the specified files Q = Exit without deleting any more files CTRL-Z = Terminate the sequence and return to command level Any other response is interpreted as "N" (NO). If "G" (GO) is entered, the question "ARE YOU SURE?" is asked in order to be sure that it is the proper response. The filespec, if given, follows the same rules as for /SE. 14. Spool the Output File (/SP) If this switch is specified then the output file (if one was specified) is spooled to the Print Spooler (PRT...). In addition, if a multiple-UIC search is being done, SRD inserts a form feed before each new UIC. PAGE 88 SRD 15. Write Back the Directory File (/WB) If this switch is specified then as well as producing a listing, SRD writes the file headers back to the UFD in the order of the listing. This means both that the UFD is compressed (which could speed up FCS operations) and that future PIP operations will proceed in the sorted order given. A particularly useful application of this is SRD [0,0]/WB which will sort the UFD files, so that SRD [*,*]/LI will then list files in numeric order of directories as well as sorted on filename, etc. Write Access to the directory is required and Write Failure is usually due to a protection violation. In the event of a write-back failure, the operation is attempted several times. 16. Use Revision Date (/RD) On the date selection, use the revision date (if any). In addition, if this is used for a /MI (/M2) listing the Revision Date will be listed instead of the Creation Date. 17. Sort the Directory (/SR) Sort the filenames. This option is turned off if the files are not being listed or written back. You can also say /-SR to get the files listed in the order they are in the directory. This is the same order that PIP lists them. 18. Include System UFD's in Wildcard Searches (/SY) If this switch is specified then all system UFD's (i.e. those with a group code between 0 and 10 inclusive) will be included in [*,*] or [*,n] searches. If it is switched off (/-SY) then such UFD's will be ignored. This switch (or it's negation) has no effect unless the group code of the specified UFD is wild. 19. Include [0,0] in Wildcard Searches (/00) If this switch is specified then [0,0] will be included in [*,*], [0,*] or [*,0] searches. If it is switched off (/-SY) then [0,0] will be ignored. [0,0] can always be listed by specifying it directly. PAGE 89 SRD 20. Treat all specifications as 'wild-carded' (/WI, /WD) One of the great powers of SRD is the ability to specify just, say, S as a filename and get a listing of all files with a filename beginning with S. It is, however, also desirable at times to be able to specify that you want only files with a filename of S on its own. The switch /WI controls this - with 'implicit wildcarding' assumed if it is specified, but not if it is negated (see /SE for an example). In addition /WD specifies whether the 'implicit wildcarding' indicated by /WI also applies during delete/purge operations (yes if specified, no if negated). Note that if /-WI is specified, FRED will still be read as FRED.*, but FRED. will only look for files (called FRED) with a null extension. 21. Select only Contiguous Files (/CO) This switch causes SRD to select only files which are contiguous. 22. Select only Locked Files (/LO) This switch causes SRD to list only files which are locked. 23. Select only Multi-Header Files (/MU) This switch causes SRD to list only files which have multiple headers. 24. Print out the current Version of SRD (/ID) This option will display the current version of SRD. 25. Print out the available Buffer Size (/SI) This option will display the size of SRD's buffer which it uses to read the directory files into memory. This switch is for diagnostic purposes only, and can be used to determine how large a directory file can be processed by SRD. 26. Attach output device if terminal (/AT) If this switch is specified then the output device (if it is a terminal) will be attached during the operation. This has the advantage of allowing CTRL-O to be used to suppress any listing, and the disadvantage of tying up the terminal during what could be a long search. If the switch is not specified the terminal will not be attached. 27. Give brief help (/HE) Typing /HE will print out a brief summary of the SRD switches. PAGE 90 SRD 4. Switch Combinations =================== All switch combinations work as would seem logical. For example, SRD /AF:7-DEC-79 10:30 /BE:7-DEC-79 14:44 would list out all files created on 7th December between 10:30 and 14:44. SRD /PU/SD will list out the files to be purged and allow you to selectively delete them. SRD /PU/-DE will list out the files to be purged, but will not delete them, and so on. Restrictions are that /DA cannot be used with /AE, /AF, /BE or /BF Only one of /SV, /OV, /PU may be used at once. Only one of /LI, /MI, /FU may be used at once. /ID, /SI and /HE cannot be used with other switches. and other nonsensical combinations (like /NA/-SR). In addition it is not meaningful to negate the switches /NE, /HV, /SV, /OV, /AE, /AF, /BE, /BF, /DA, /SE, /PU, /SD, /ID, /SI or /HE. 5. Switch Defaults =============== Default values for the switches are set at Task-Build time, and may vary from installation to installation. Any of the switches may be preset in this way, but usually the only ones affected are /LI, /NA, /RD, /SR, /SY, /AT, /00, /WI, /WD, and /M2. If in doubt about the defaults on your version consult your System Manager, or experiment with a few options (like [*,*]/LI to see if /SY and/or /00 are set) to determine which are set. PAGE 91 SRD 6. Error Messages ============== 1. SRD -- DIRECTORY TOO BIG! RERUN WITH LARGER INCREMENT! SRD was unable to expand its buffer sufficiently to hold the whole directory at once. 2. SRD -- CMD READ ERROR! Either an error occurred in reading the command line, or a comma was specified other than in the UIC of the Input or Output Filespec. 3. SRD -- CMD SYNTAX ERROR! The command line failed to parse correctly, and is therefore invalid. 4. SRD -- ERROR IN INPUT SPEC! An invalid input filespec was given. 5. SRD -- ERROR IN OUTPUT SPEC! An invalid output filespec was given. 6. SRD -- ERROR READING MFD! An error occurred while SRD was trying to read the Master File Directory. 7. SRD -- PARSE ERROR! The output filespec could not be parsed correctly. 8. SRD -- OPEN ERROR ON INPUT! SRD detected an error opening an input file. 9. SRD -- OPEN ERROR ON OUTPUT! SRD detected an error opening the output file. 10. SRD -- DIRECTORY FIND ERROR! A directory was specified which does not exist. 11. SRD -- NO SUCH FILE(S)! No files were found to match the input specification. 12. SRD -- INVALID DATE FORMAT --- ENTER DD-MMM-YY HH:MM (1-JUN-76) Dates must be entered in the form DD-MMM-YY HH:MM (or vice versa) or DDMMMYY HH:MM (or vice versa) with the single exception that the date may be abbreviated to one character. PAGE 92 SRD 13. SRD -- ERROR READING FILE HEADER! SRD detected an error while trying to read a file header. 14. SRD -- PUT ERROR! An error occurred while trying to output a record to the output device. 15. SRD -- WRITE ERROR! An error occurred while trying to write back a directory. 16. SRD -- READ ERROR! An error occurred while trying to read a directory. 17. SRD -- ERROR DELETING FILE! An error occurred while trying to delete a file. 18. SRD -- DIRECTORY PRIVILEGE VIOLATION! The user does not have the required read/write access to the given directory. 19. SRD -- DIRECTORY OPEN ERROR! An error occurred while trying to open a directory file. 20. SRD -- DIRECTORY WRITE-BACK ERROR! An error occurred while trying to write a directory back into the directory file. 21. SRD -- WRITE-BACK CANCELLED--CAN'T FIT ENTIRE DIRECTORY IN CORE! A write back was requested (/WB) but cannot be performed as the directory has only been sorted in chunks. 22. SRD -- FILE ID-SEQUENCE NUMBER MIS-MATCH! An attempt to read a file header failed because of a file ID and sequence number mismatch. 23. SRD -- HEADER READ-PRIVILEGE VIOLATION! The user did not have valid access rights to read the file header for the specified file. PAGE 93 TASKER TASKER.DOC TASKER IS A UITLITY FOR PATCHING TASK IMAGE FILES ON DISK. IT HAS THE FOLLOWING CAPABILITIES: (1) DESCRIBE TASK SEGMENTS: GIVES BEGINNING AND ENDING ADDRESSES (PC VALUES) OF OVERLAY SEGMENTS AND/OR READONLY PSECTS. THE ADDRESSES CORRESPOND TO THE ONES IN THE TASKBUILD MAP, AND APPEAR IN IDENTICAL SEQUENCE. ALL REQUESTS TO THE PROGRAM CONCERNING A SPECIFIC ADDRESS MUST INCLUDE ITS SEGMENT NUMBER. (2) DISPAY MACRO SOURCE CODE: DISASSEMBLES A REQUESTED SECTION OF THE TASK. IF REQUESTED, THE PROGRAM WILL TRY TO DISAS- SEMBLE DATA. (3) REPORT TASK CONTENTS IN ANY OTHER FORMAT: WILL DISPLAY STOR- AGE A WORD AT A TIME AS ASCII, OCTAL WORD, OCTAL BYTE, OR AS RAD50 TO BE TRANSLATED INTO ASCII. (4) SEARCH FOR SPECIFIED CONTENTS: WILL SEARCH FOR ONE TO TWO WORDS, TO BE ENTERED IN ANY OF THE FIVE FORMATS NAMED ABOVE. THIS FEATURE IS HANDY TO LOCATE A SECTION OF CODE OR DATA TO BE CHANGED IF A TASKBUILD MAP IS NOT AVAILABLE. (5) UPDATE SPECIFIED LOCATIONS: OLD CONTENTS ARE DISPLAYED AS OCTAL WORD; NEW CONTENTS CAN BE ENTERED IN ANY OF THE FIVE FORMATS NAMED ABOVE. (6) DESCRIBE THE TASK HEADER: GIVES USEFUL INFORMATION IN AN EASILY READABLE FORMAT. PAGE 94 TPC TPC - Fast Tape Copy ==================== Users' Guide ============ This program will copy a complete magtape to a Files-11 disk and store it there in a special image mode, from which it can create one or more copies of the tape (must faster than FLX ever could). BIGTPC is able to do this, but also will handle any block size on tape up to 4200. bytes (big enough for BRU tapes). By going from 4 to 3 buffers for tape and smaller numbers of disk blocks per read/write still larger tape block sizes can be handled. Also, several additional switches are supported. If it is desired to support larger BIGTPC block sizes, it is possible to reduce the number of BIGTPC buffers (and the buffer headers) and to reduce the disk buffer count of blocks. This works well with the number of disk blocks reduced to 8., the number of BIGTPC buffers reduced from 4 to 3, and the size increased to 11000. bytes, supporting image copies of such formats as VMS BACKUP or UNIX TAR tapes. Note however that where these counts are changed, BIGTPC may not terminate correctly when writing a container file from another version. You may have to abort and write EOFs with another utility. If you have a tape and recreate container files, there will be no trouble. The command format is:- TPC Output-filespec=Input-filespec where one of the 'filespecs' must be a magtape device (e.g. MT:) and the other the name of an image file on disk. Legal switches are:- /BL:nnnn - Specifies an initial allocation specification for the image file if a disk is the output device. Defaults to 200. /SA:nnnn - Specifies a secondary allocation specification for the image file if a disk is the output device. Defaults to 50. /CO - Specifies that the disk file is to be contiguous /HD - Indicates High Density (1600 BPI) tape is to be written. (For TE16, tape is read at the proper density automagically.) This permits a container file from one density to be written out in another. PAGE 95 TPC /NR - Specifies NO positioning of the tape prior to the start of copying. This will allow TPC to merge several backup collections on a single output tape if used with care. After the end of a copy, TPC will write 4 EOF records and backspace so that it will be positioned after the first EOF on tape. This will ensure that a second backup done with the /NR switch will correctly copy onto a FLX tape in readable fashion. /SC:nnnn - Sets tape characteristics to nnnn(octal), to allow use of tapes with even parity, 556BPI, etc. If the /HD switch is used, the high density bit is ORed in with the nnnn value specified in the /SC switch. /AN - Specifies possible ANSI format. If TPC sees this switch it will look for ANSI label records and permit copies even where the tape has null files and hence double EOF before the real end of tape. Only 80 byte records are examined and EOFs are treated specially only between HDR2 and EOF2 (or EOV). The headers are assumed to be in ASCII unless the switch /EB is given, in which case they are assumed to be in EBCDIC. If the tape is not really an ANSI format tape, the TPC copy operation is not changed. Thus the /ANsi switch may be used on a tape of unknown format. The default is /AN, and to force BIGTPC NOT to look for ANSI labels (looking normally only at 80 byte records unless the /RT subswitch is used), use the /-AN switch. /EB - This subswitch of the /AN switch forces on ANSI label checks but causes TPC to look for EBCDIC header labels rather than ASCII. Note that TPC looks for either ASCII or EBCDIC, not both. The default is not to look for ANSI labels and end copy at double EOF; the /AN or /EB switch settings allow some modifications to this. /RT - Use RT11 type "ANSI" labels. RT11 may not make label records 80. bytes long, and if you have RT11 tapes, the ANSI checks will normally ignore the RT11 ANSI labels unless you use this switch. It causes BIGTPC to ignore length of records and checks everything to see if it is an ANSI label record. It is not a very good default because it probably can be fooled easily but may be needed for RT11 tapes. /ER - Specifies that TPC will ignore errors on tape. This specifically means that all errors except EOT/EOV/EOF will be ignored. This is quite useful for recovering data from tapes which are old and full of errors, or for writing an output to a tape with bad spots (though it won't cure bad spots and this method of writing anyway is not necessarily a good idea...). PAGE 96 TPC /FR - Rewind the tape after copying to it. Note the /NR switch applies to BEFORE the tape is used and inhibits positioning at that time. The /FR switch will rewind the tape AFTER writing to it. /TR - This switch allows BIGTPC to read a disk to a container file as though it were a tape. It implies BIGTPC should act as though the input device were a tape even if it is not. BIGTPC will need to know the size to copy (defaults to 494. blocks, the size of an RX01) and the start block number (defaults to 0,0) as octal numnbers in the form low:high (see /SZ and /LO switches). The input device is copied 1 block at a time. The normal "control" features like density, rewind, etc., are suppressed UNLESS the /CT switch is used. Their effect is not likely to be meaningful. /TW - This switch allows BIGTPC to write a container file to a disk as though the disk were a tape (on the output side of the command line). It is the inverse of the /TR switch and needs the /SZ and /LO information too. /SZ:low:high - This switch sets the device size for /TR, /TW, and /IM copies, in 2 words of block counts. Note the number of blocks is given, not the last block number, so a disk with 494 blocks is specified as /SZ:494., the high size defaulting to 0. Default value is /SZ:494.:0. /LO:low:high - This switch specifies the starting physical block of the disk to begin transfer from in /TR and /IM, or transfer to in /TW cases. This allows you to move blocks around or to copy only parts of a disk. The default is 0:0, so you won't need to use /LO often unless you intend to copy partial volumes. /CT - This switch allows control-type QIO's to occur even if /IM, /TR, or /TW are specified. These QIO's do things like rewind, write endfile, space forward or back, and set density as well as attach the LUNs. It is not very meaningful for /TR or /TW unless you have a strange device that nevertheless is really a tape (and it's not certain you can emulate it properly this way anyhow). For /IM copies, it allows a tape to be the output device and to receive a blocked copy of a device in format independent ways while still setting density, rewinding, etc. Note the control QIOs are not error checked so if you try to rewind a disk, it'll not hurt you. PAGE 97 TPC /IM:low:high:blkfactor - This switch allows BIGTPC to copy data in image mode directly from one device to another. It does not operate AST driven in this mode as it does in all others, but uses all buffers as one large I/O buffer permitting I/O transfers of up to about 72. blocks at a time. The low:high arguments are the block number to begin the output transfer to on the output device (/SZ specifies the length in blocks to move), and the "blkfactor" argument is the number of blocks to be transferred at each QIO$ to the output device. This defaults to 8. so that if the output device is tape, the buffers will be 4096. bytes long. If you specify a bigger blocking factor than BIGTPC can handle, it will just use its maximum. Normal operation will not issue any "write-EOF" operations, but if tape is the output device, the /CT switch will permit these controls to be done so the resulting tape will work (and the /FR switch, the /HD switch, and the /SC switch will work). /FL:filnam -This switch works only with the /IM and /CT switches and will have no effect unless BOTH of these are specified. It causes BIGTPC to write a standard DOS format (FLX format) label record before it writes an image file on tape, using "filnam" (up to 6 characters) as the filename. The full file specification is [1,1]filnam.OLB with standard DOS protection and a creation date of 00-JAN-70. This permits the image file to co-exist on a FLX tape (.OLB is the extension chosen since FLX will copy it in image mode). FLX can skip the nonstandard file and make directories, read, or write on the tape, allowing it to contain other interesting programs (perhaps a copy of BIGTPC to read the images with, for instance). Also, multiple files may be more easily kept on the tape. On input, you must skip this record on tape prior to inputting the file. If /ER is specified, zero byte reads will NOT terminate copies (so sizes better be right!) and lengths copied will be calculated from given block factors, not from returned actual byte counts. /NI - This switch ("Nibble In") allows /IM copies to read a disk 1 block at a time instead of using big QIOs of "blkfct" blocks at a time. Thus, if there is a bad disk block, data on following blocks will not be lost. See the /IM switch doc. for interaction with /ER. /NO - This switch ("Nibble Out") allows /IM copies to write a disk 1 block at a time. It is supplied also to aid output to a disk with bad blocks, guaranteeing that not more than 1 block's data will be lost. Its interaction with /ER is like /IM. The /NI and /NO switches apply only to the /IMage mode copies of BIGTPC. PAGE 98 TPC /HE - This switch causes BIGTPC to print a help message summarizing the action of all of its switches and giving the defaults for the more important ones. So that, for instance, TPC BACKUP=MT: will create the file BACKUP (.DOS by default) from the magtape on MT:, and TPC MT:=BACKUP would then create an exact copy of the original magtape onto the tape now mounted on MT:. Note that TPC will only handle one tape at a time and cannot handle block sizes of greater than 4200 bytes without edit and rebuild. If the tapes are FLX format tapes, however, the TPCDIR program ([312,315]) may be used to list directories or extract copies of files in the container file, though in a fairly cumbersone way. Otherwise, BIGTPC acts as a format-independent tape copy to EOT (signalled by 2 consecutive EOFs). CAVEAT: It is possible for a FILES-11 tape to have 2 EOFs in a row where a zero length file is copied, yet not be at EOT. If the tape you are copying may be of this sort, use the /ANSI switch while copying (or the /EBCDIC switch if it came from an IBM site using EBCDIC labels). This will allow TPC to correctly handle double EOFs in the middle of a file. If your tape does not have this pathology, TPC will function correctly also, so the /ANsi switch is a good one to set mast of the time unless you some sort of pseudo-ANSI tape that may have have records starting with HDR2, EOV, or EOF. If your tape was produced by RT11 PIP (possibly also under RSTS), you may need the /RT switch to successfully handle null files. The /ANsi switch is now on by default; use /-AN to turn it off if you must. PAGE 99 TPC TPC can report the following errors:- 1. TPC - DISK I/O ERROR. CODE = n TPC encountered an error while reading from/writing to the disk. 2. TPC - MAGTAPE I/O ERROR. CODE = n TPC encountered an error while reading from/writing to the magtape. 3. TPC - COMMAND LINE INPUT ERROR TPC encountered an error in reading the commandline. 4. TPC - COMMAND LINE SYNTAX ERROR TPC encountered an error when trying to parse the command line. 5. TPC - INVALID SWITCH The commandline contained a switch that TPC could not recognise, or a file specification that it could not parse. 6. TPC - OPEN ERROR ON OUTPUT FILE A file was specified as output, but TPC encountered an error when it tried to open it. 7. TPC - OPEN ERROR ON INPUT FILE A file was specified as input, but TPC encountered an error when it tried to open it. 8. TPC - SPECIFY 1 FILE & 1 MAGTAPE DEVICE The commandline either specified magtape as both input and output device, or a disk file as both input and output device. TPC tends to crash when it has an allocation failure while reading tape to disk. PAGE 100 TWOPAGE Instructions for TWOPAGE The following proceedure can be used to produce manuals from ru- noff text. The resultant manual will be printed on both sides of the 9&1/2 X 11 paper with perforated edges. The sprocket feed edges can be easily removed to produce a standard size 8&1/2 X 11 manual. 1. Runoff source should specify the following: 1. .LEFT MARGIN 10 2. .RIGHT MARGIN 74 3. .PAPER SIZE 58,74 4. The output file should have the standard ".DOC" file type specification 2. After using RNO to produce the "XXXXXX.DOC" file, run the basic program "TWOPAGE" via the command line: BA3 DP:[1,1]TWOPAGE/RN "TWOPAGE will do the following: 1. Seperate the "XXXXXX.DOC" file into the files "XXXXXX.LFT" and "XXXXXX.RGT" 2. Append another "FF" character to "XXXXXX.LFT" if necessary to make the total number of pages of each file equal. 3. Change the printer you wish to use to FORM TYPE 2 (to ensure that no other output is queued to it,) via the command: OPR LP1:/FO:2 4. Load the 9&1/2 X 11 paper in the printer and verify printer is at TOP-OF-FORM with paper properly aligned 5. Mark the starting page so one can return to that point after printing the "right-hand" pages. 6. QUE LP1:/FO:2=XXXXXX.RGT(/CO:N) (number of copies is optional) 7. When printing of right pages is finished, Remove printer output with 1 or 2 extra blank pages PAGE 101 TWOPAGE Instructions for TWOPAGE PAGE 2 8. Align paper to same fan-fold as in step #4 above 9. QUE LP1:/FO:2=XXXXXX.LFT(/CO:N) (same number of co- pies as above) 10. After "left-hand" pages have finished, re-load printer with standard paper. 11. Return printer to standard FORMS TYPE via the command: OPR LP1:/FO:2 Frank R. Borger Michael Reese Medical Center Department of Medical Physics March 20, 1978 PAGE 102 VOL VOLUME CHARACTERISTICS COMMAND (VOL) FUNCTION: The VOLUME CHARACTERISTICS command (VOL) provides a means for changing volume characteristics for a previously initialized Files-11 volume. It takes most of the switches that INITVOL takes, and these are specified exactly as for INITVOL. Note however that no volume label is given after the device specification. FORMAT: VOL[UME] device:[/keyword(s)] where: device: specifies the device containing the volume to be acted upon. keyword(s) are one or more of the following: /UIC /PRO /MXF /EXT /FPRO /CHA /WIN /LRU /LABEL See INITVOL documentation for an explanation of the above switches, except for LABEL, which has no INITVOL switch equivalent. This switch permits the volume label to be changed. If LABEL is given with no arguement, the volume label is cleared. EXAMPLES: 1. MCR>VOLUME DK3:/LABEL=BILL Rewrite the volume label on the Files-11 disk on DK3 so that it reads "BILL". 2. MCR>VOLUME DT0:/FPRO=[RWED,RWED,R,R] Change the default file protection for the dectape on DT0 so that all subsequent files are written with the default protection [RWED,RWED,R,R], allowing only read access to all but the file owner. 3. MCR>VOLUME DK2:/UIC=[55,70]/LABEL= Change the UIC information on the disk on DK2 so that the owner of the disk is user [55,70]. Also clear the volume label. PAGE 103 XMT xmt - intercomputer communications task 12-Jan-82 Overview -------- XMT is a utility task which provides a convenient means for data transfer between the the Medical Physics PDP11 and any other com- puter system that is accessible with a standard terminal by ei- ther hard-wired lines or by dial-up modem. XMT makes your termi- nal appear as though it were connected directly to the "remote" computer system. Data transfer is performed by producing textual output from the remote computer (e.g., program listings, computer runs, etc.) and, through XMT, routing that text to a disk file at the PDP11. The reverse path takes a file at the PDP11 and "types" it to the remote. PAGE 104 XMT 12-Jan-82 CHAPTER 1 Using XMT XMT is a standard MCR function, evoked by: MCR>XMT XMT prints the message: Terminal Transmission Program V3.3 Initializing operation using TT25: If TT25 is connected to a dial-up modem you must now dial the re- mote computer before continuing. If the terminal is hardwired to the remote system, or when you have made the connection to the remote via modem, XMT is ready for operation. XMT is now running with several defaults in effect: 1. ASCII transfer mode. XMT expects files to be in ASCII format, (i.e. source, listings, etc.) 2. COPY mode is off. When receiving a "file" from the remote terminal, char- acters typed at your terminal are not echoed to the out- put file. 3. DELAY of 20 milliseconds. XMT will wait 20 milliseconds after receiving a "prompt" character from the remote terminal, (usually a line-feed) before transmitting the next line of a file to the remote computer. 4. ECHO Mode is off. When file transfer is in process, all I/O is not printed on your terminal. A single flag character is printed for each line transferred. 5. PROMPTED transmission is on. XMT waits for a Line-Feed (or some other character) be- fore transmitting the next line of a file from the PDP11 to the remote computer. PAGE 105 XMT Using XMT PAGE 1-2 12-Jan-82 6. Several control characters are re-defined (see appendix) Since ^C is used to inform XMT that you wish to change some operating condition, if you wish to send a ^C to the remote computer, typing a ^B will cause a ^C to be sent to the remote computer. Note that although several other re-defines are normally set, under IAS, only the ^C re-define is necessary. 7. FULLDUPLEX mode is on Characters typed at your terminal are not echoed local- ly, the remote computer must echo them. 8. 8-BIT ASCII mode is off, no parity Characters are transmitted with 7 data bits and the par- ity bit off. These settings can be changed dynamically by the user to tailor XMT's characteristics to ease communication with other computers. This version of XMT has been modified for IAS (basically a rewrite of the terminal I/O sections) by G. Everhart. In normal operation, it uses TT25 for connection to the "remote" computer. TT25 should normally be set up at system boot, but if necessary one may have to reset it to: MCR>SET /UIC=[1,1] ;To change another Terminal setting MCR>TER TT25:/FULLDUPLEX ;fix for no echo, full duplex I/O MCR>TER TT25:/BINARY ;fix for no special ^C recognition MCR>TER TT25:/WIDTH:132 ;make width big enough This should allow the terminal to work correctly. Note that you'll have to try various options when using it with non-DEC systems. In its default state, it works well with other IAS or RSX11M systems. You will have to reset the characterstics of TT25 to permit someone to connect a terminal to it and have it work correctly. Also, by the nature of the program, (it uses single-character QIO's for I/O to your terminal) will sometimes result in a noticable delay in output (or echo) at your terminal. However, it appears to work reliably once the right operating conditions and defaults are established. To leave XMT, type CTRL/C twice (CTRL/C is typed by holding down the CTRL key and typing C), or by typing CTRL/C followed by X (eXit). PAGE 106 XMT 12-Jan-82 CHAPTER 2 XMT Options To change any of the program settings/options, type CTRL/C fol- lowed by the upper case character signifying the setting/option desired. Below is a table of options and their corresponding de- finitions: NOTE Do NOT type a carriage-return to enter or execute any of these commands. Typing the single character of the com- mand is all that you need to execute that option. A - Changes the file transfer mode to ASCII if in the binary mode, or changes the file transfer mode to binary if al- ready in the ASCII mode. B - Sets the BREAK (logical spacing) key definition to some keyboard character which, when depressed, creates a 'BREAK' condition to occur just like the 'BREAK' key on a teletype. C - Enter/exit Copy mode; i.e., when receiving a file from the remote in ASCII mode, all characters typed at the keyboard are copied to the output file when also in Copy mode. D - Set the length of delay that XMT should wait after re- ceiving a prompt character before sending the next line of data from a disk file at the PDP11. The delay can range from 0 to 99, where 0 corresponds to no delay and 99 corresponds to 99 clock ticks (approximately 1 2/3 seconds). If the length of the delay is a single digit, typing a carriage-return after typing the digit will be sufficient to enter the delay. You may also enter a single digit for the delay by preceeding it with a zero. You cannot enter a delay of more than two digits. Any characters entered other than 0 through 9 will cause the default delay of 20 to be used and no error message will PAGE 107 XMT XMT Options PAGE 2-2 12-Jan-82 be given. E - Enter/exit Echo mode; i.e., when receiving or transmit- ting a file all input/output from/to the PDP11 disk is printed on the user terminal. This mode is useful when you wish to see the effects of transmission in progress. In general, this mode should only be used when you are logged onto a high-speed terminal or when the amount of printing is less than 2 full pages (at 1200 baud) or in- definitely (at 300 baud or less). F - Receive a file From the remote. A short status of the applicable options in effect is printed before a file specification is requested. The file specification is 29 or fewer characters and follows the system standard conventions for files. Entering a name of less than 29 characters requires a carriage-return to enter the fi- lename. The RUBOUT or DELETE keys can be used to edit out any errors made in typing the file spec. Entry of a null, or empty, filename will allow you to exit the F option without sending any data or creating any files. Any previous execution of the F option that was not ter- minated by either the O option or by exitting XMT is au- tomatically terminated prior to the printing of the short options-in-effect summary. H - Prints a very brief Help summary of the purpose of each option. I - Terminates reading input from a PDP11 disk file if such a file transfer was taking place. The message "Transmission Complete" will be printed if a file transfer is terminated, otherwise no action is taken. This option is useful in aborting the transmission of data to the remote if problems in communication arise. O - The O option performs the same function for terminating a file receive operation (Output to the PDP11 disk) that the I option performs on file transmit operations (Input from the PDP11 disk). This option is the only means, other than by exitting XMT or by starting another file receive operation, of signalling the end of a receive operation to XMT. The message "Receive complete" prints when a receive operation is terminated. P - Change transmit file mode from Prompted mode to Prompt- less, and vice-versa. A message is printed indicating which mode is in effect. When changing to prompted mode you are asked which character sent by the remote com- puter system should be used as the prompting character. Type the prompting character and XMT will, during a file transmit operation, wait for this character to be re- ceived from the remote computer before sending the next PAGE 108 XMT XMT Options PAGE 2-3 12-Jan-82 line of information to the remote. Note that XMT will send the first line of input to the remote computer without waiting for the prompt, but all other lines of input will wait for a prompt to be received before they will be sent. R - Redefine/don't redefine control characters. This option enables and disables the user-defined translation table for control characters as described under the "^" op- tion. A message is printed which mode is in effect. When in "Redefine mode" XMT will use a translation table to convert any redefined control characters to some oth- er control character so as to be able to "type" reserved control characters to the remote computer. Examples of reserved control characters are CTRL/C, CTRL/O, CTRL/S, CTRL/Q, etc. "Not redefined mode" disables this trans- lation, but the translation table is not destroyed. S - Prints a Status of the options in effect for XMT. The status report includes information about parity, ASCII or binary modes, information about file transfer opera- tions, and prints the definition of the BREAK character, if any. T - Starts a file Transmit operation. This option is very similar to the F option except in the direction of data transfer. A check is made as to whether or not XMT was in the midst of a previously started file transmit oper- ation, and if so, that transmit operation is terminated. A short status of file transmit options-in-effect is printed before you are requested to type in the name of the file you wish to transfer to the remote system. If you just type a carriage-return, XMT simply returns without initiating a file transfer. Otherwise you must enter a file name in the standard system format. If the name of the file you enter does exist on disk a message is printed indicating that the file is not found and no transfer operation is initiated. Otherwise a file transfer is initiated which can be terminated by 1) ex- itting XMT, 2) using the I option, 3) using the T option again and entering a carriage-return for the name, or by 4) reaching the end of the input file. The message "Transmission complete" is printed when the transfer op- eration is completed (or terminated). U - Unduplex or duplex the XMT program. In the Unduplexed mode characters typed on the terminal are not echoed to the terminal unless the remote computer performs the echoing. This mode is useful when communicating to com- puter systems as other PDP11's. For communication with systems such as TSO, however, the Duplexed mode is re- quired if you wish to see the characters that you type. PAGE 109 XMT XMT Options PAGE 2-4 12-Jan-82 X - EXit XMT. All file transfers, if any, are terminated and control is returned to the RSX-11M Executive. 8 - Enter 8-bit ASCII mode and exit 7-bit ASCII, or leave 8-bit ASCII and enter 7-bit ASCII and be asked what par- ity you desire. This mode allows you to determine whether or not the information you transmit and receive will be full 8-bit ASCII or 7-bit ASCII with software generated even, odd, mark, or no parity. Some computer systems require specific parity settings, but other PDP11's and TSO don't care. ^ - Allows you to redefine a control character as a differ- ent control character. This allows you to use some oth- erwise reserved control characters, such as CTRL/C, and allow you to send these characters to the remote system. You will be asked to type two characters. The first character you type will be the redefined character and the second character you type will be the definition. To enter either of these characters may, and sometimes must, enter the upper-case equivalent of the control character. The characters you type are automatically converted to the proper control character and their upper-case equivalent is printed after you type the character. For example, you wish to use the character CTRL/W to signal when you transmit a CTRL/C. Type the ^ option, the letter W, and the letter C and the redefini- tion has been set. Assuming that XMT is in "Redefine mode", every time you type a CTRL/W a CTRL/C is actually sent to the remote system. If you wish to change a de- finition, simply redefine it in the manner given above. PAGE 110 XMT 12-Jan-82 CHAPTER 3 Summary of Capabilities 1. Full or half duplex operation 2. Disk file transmit and receive 3. Prompt character checking and delay 4. Optional echoing of files during transmission and recep- tion 5. A short help message summary 6. The ability to transmit a file while also receiving another file 7. The ability to transfer files using a full 8 bits 8. The capability of transferring files with or without prompted handshaking 9. The option of preventing everything entered at the user terminal from being copied to an output disk file during a receive operation 10. The ability to create a 'BREAK', or logical spacing, condition so as to be able to interrupt remote devices such as TSO 11. The capability of defining almost any keyboard character to be used to signal when a BREAK was desired 12. The ability to perform translations of control char- acters entered at the user terminal to characters not normally able to be entered without interception by RSX-11M 13. The ability to turn on and off the control character translation without losing the previous definitions 14. The inclusion of a "status" subroutine which enables the PAGE 111 XMT Summary of Capabilities PAGE 3-2 12-Jan-82 user to see what parameters are currently in effect for the program 15. The ability to set the mode of parity (even, odd, mark, or none) to be used when transmitting each character to the remote while the 7-bit character mode is in effect. PAGE 112 XMT 12-Jan-82 APPENDIX A XMT Default Control Character Definitions Typed Character Resulting Character ctrl/A ctrl/S ctrl/B ctrl/C ctrl/P ctrl/O ctrl/W ctrl/Q ctrl/X ctrl/Z List of XMT commands A - Change file transfer mode (Binary/Ascii) B - Set BREAK character C - Enter/exit copy mode D - Set length of delay (in ticks) E - Enter/exit echo mode F - Recieve File from remote computer H - Prints HELP summary I - Terminate transmission to remote computer O - Terminate reception from remote computer P - Enter/exit Prompted transmission mode R - Redefine/don't redefine control chararacter mode S - Print current program status T - Transmit file to remote computer U - Enter/exit full duplex mode X - Exit XMT 8 - Enter/exit 8-bit ASCII mode ^ - Redefine control character