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-11M 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. 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. 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 then Ascending on File Name 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) 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. 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). /BE 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). 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. 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. 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. 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. 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. 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. SRD - Sorted Directory Utility ============================== System Guide ============ 1. Task Structure ============== SRD consists of fifteen modules, in the following strucutre:- SRDROT ! SRDATA ! SRDSUB ! SRDTRP ! ------------------------------------------------------------- ! ! ! ! ! ! SRDINI SRDNUD SRDOPR SRDSRT SRDDBF SRDLST ! ! ! ! SRDREP SRDXX1 SRDXX2 SRDTST ! SRDXX3 (Note that some routines from SYSLIB are also overlaid). 2. SRDROT ====== SRDROT is the high-level module that controls all the others. It first calculates the top of the re-usable task space (see write-up on SRDXXn) and the minimum size of buffer required (the difference between that and the top of the code). It then calls SRDINI to get a command. If the request was /ID it outputs the Version Number message and returns to call SRDINI for another input line. If the request was /SI it calls SRDDBF to calculate the current buffer size and returns to call SRDINI for another input line. In all other cases it calls SRDOPR and SRDSRT to access each directory, SRDLST to output any listing and SRDNUD to access the next UIC (if a wildcard was specified). It is also responsible for spooling the output file if required. 3. SRDATA ====== SRDATA merely contains all the global data used by the task. 4. SRDSUB ====== SRDSUB contains four commonly used subroutines:- ATTDET - which attaches to or detaches from a given device. CNVDAT - which converts an ASCII date and time into an internal format. Note that CNVDAT has two subsidiary entry points (CVDATE and CVTIME) if only the date or time on their own are to be converted. SRDCOM - which compresses a directory in the input buffer ALERR - which is called by various routines (including $AUTO) when an Executive Directive fails. Currently it simply puts the return address in R0 and the contents of the DSW in R1 and issues a HALT (which will terminate the program with a register dump) but should really be made rather more intelligent. 5. SRDTRP ====== All errors are logged by executing a TRAP instruction. These are trapped by SRDTRP which formats and outputs the relevant error message and then exits. While very easy to implement this is a rather noddy method of error reporting and should really be improved. 6. SRDINI ====== SRDINI first shrinks the task back to its basic size (this is not really necessary as SRDOPR will do it if necessary). It then sets the default values for the switch masks, zeroes all the valid data areas and gets the next command line from the user (via GCML$), calls SRDREP to replace any illegal characters and then parses it via CSI. If the user requested help (/HE) it supplies it (via a spawn to MCR) and prompts for another line. It opens the output file (if any were given), interprets and sets up dates for the /DA, /AE, /AF, /BE and /BF switches and then sets up the filename block for the (first) required directory. 7. SRDREP ====== SRDREP simply checks the command string for characters that CSI will object to, and replaces them. Otherwise, expressions like: SRD /DA:10:30 or SRD /SE:;1 would be truncated. 8. SRDOPR ====== SRDOPR opens the current directory file, unless it is already open, and finds out how large it is (or how much more there is to be read into memory). It then attempts to extend/contract SRD until the buffer is the same size as that required for the directory (or what remains of it). [Note that it must ensure that SRD maintains at least the minimum buffer calculated in SRDROT, or the next attempt to load in the SRDINI overlay will fail.] If that fails it merely extends SRD as far as it can. It then attempts to read in as much of the directory as it has found room for. It then compresses the buffer and, if more directory was needed, tries to read in some more until it either has all of the directory in memory, or can compress the existing buffer no further. 9. SRDSRT ====== SRDSRT first compresses the directory, by moving the entries up over unused slots. It then sorts the entire directory (by checking all entries for the first and putting it first, then all the rest for the second and so on). [This is horribly inefficient for large directories, but as quite adequate for directories of 200 or so files.] If /WB was specified and the whole directory is in memory, it is written back into the directory file. 10. SRDNUD ====== SRDNUD reads the MFD to find the next directory that matches the wildcard search requested. 11. SRDLST ====== SRDLST examines each entry in the directory in the buffer in turn. First it checks the version number, if /HV was specified. If that qualifies, it converts the directory name to ASCII in the output buffer and, if a filename was specified (directly or via /SE or /SD), calls SRDTST to check it. If the match fails and /NE was not specified (or vice versa) the name is ignored. Otherwise it checks the current (and adjacent) version to see if the filename qualifies under any /SV, /OV or /PU switches. If it does, it checks to see if it qualifies under any /CO, /LO or /MU switches. If that matches it checks to see if it qualifies under any /AE, /AF, /BE, /BF or /DA switches. Once it has been determined that the given file specification matches that requested, the module formats the output line(s) according to the type of listing requested. If /SD was specified it then prompts the user to see if he wants the file deleted. If /DE or /PU was specified, or /SD and the user answered Y this time, or G previously, the file is deleted. The routine then returns to check the next entry. When all the entries have been checked the routine outputs the trailer line for the directory. 12. SRDTST ====== SRDTST checks an individual filename to see if it matches up to the selection criteria laid down by a specified input filename, or a /SE switch (q.v.). 13. SRDDBF ====== SRDDBF merely calculates the amount of space in the buffer and outputs a message accordingly. 14. SRDXX1/2/3 ========== SRDXX1, SRDXX2 and SRDXX3 are used to enable SRD to reclaim some space. Each defines a PSECT that will follow all others in a segment ($$$XXn) and a global symbol to locate that PSECT (XXn). One is attached at the end of each of the three longest segments, not counting SRDINI. The idea is that once SRDINI (which is the longest path in the task) has parsed the command line, the later modules can reclaim the extra space it required as buffer space, and they do this by SRDROT working out from the SRDXXn modules, where the longest segment (of the others) ends. This is a potentially tricky method, but appears to work at the moment in overlaid or non-overlaid versions of SRD. If SRD starts crashing with errors from $AUTO it is probably something to do with these. 15. SRDSYS/SRDPRE ============= These are two prefix files used in assembling the SRD modules. SRDSYS simply contains the system-specific definitions (such as Operating System, existence of EIS and such-like) and is created by SRD.CMD. SRDPRE conatins definitions of all the local symbols (such as the switch bit settings) and macros used in SRD. 16. Assembling/Building SRD ======================= SRD is assembled and built by means of the command file SRD.CMD. On the first time through SRD.CMD it will ask questions relating to what system you are running on (to create SRDSYS.MAC) and to what default switch settings you want for SRD (and will create SRD.BLD and SRD.ODL). In future invocations you can use these files without having to create new copies each time. SRD is a non-privileged task, with 4 units and a taskname of ...SRD. It should be task-built with the following options:- TSKV =SSTVC$:7 STACK =128 ASG =TI:1 ASG =SY:2:3 ASG =TI:4 UNITS =4 GBLDEF =..RWLG:1 GBLDEF =SWINI:n GBLDEF =SW2INI:133500 SWINI defines the initial switch settings of the first mask:- 2 = /LI - List the directory 100000 = /NA - Sort by Name first SW2INI defines the initial switch settings of the second mask:- 40 = /RD - Use Revision Date for date checks 100 = /SR - Sort the directory 400 = /SY - Include system accounts in [*,*] 1000 = /AT - Attach output device if terminal 2000 = /00 - Include [0,0] in [*,*] 10000 = /WI - Implicit wildcarding 20000 = /WD - Implicit wildcarding in delete 100000 = /M2 - Type 2 Middle Size Listing The overlay used currently is:- .NAME OV1INI .NAME OPNFNB .NAME PRSFNB .NAME CSI12 .ROOT SRDR-*(O1,O2A,O2B,O2C,O4,O5) SRDR: .FCTR SRDROT-SRDATA-SRDSUB-SRDTRP-LIBR LIBR: .FCTR LB:[1,1]SYSLIB/LB:ASSLUN:ARITH:CBTA:DIRECT:DEL:EOFCHK-LIBR2 LIBR2: .FCTR LB:[1,1]SYSLIB/LB:MKDL:MOVREC:PGCS:RDWAIT:RETADR:WATSET O1: .FCTR SRDINI-SRDREP-*(O11) O2A: .FCTR SRDNUD O2B: .FCTR SRDOPR-SRDXX1 O2C: .FCTR SRDSRT-SRDXX2 O5: .FCTR SRDDBF O4: .FCTR SRDLST-SRDTST-LB:[1,1]SYSLIB/LB:PUTSQ-SRDXX3 O11: .FCTR OV1INI-*(OP1,PRS1,CSI1) OP1: .FCTR OPNFNB-LB:[1,1]SYSLIB/LB:OPFNB:$PRINT PRS1: .FCTR PRSFNB-LB:[1,1]SYSLIB/LB:PARSE CSI1: .FCTR CSI12-LB:[1,1]SYSLIB/LB:.CSI1:.CSI2 .END