SRD -- The DECUS Sort Directory Utility ---------------------------------------------------------------- SUBJECT: SRD -- The DECUS Sort Directory Utility AUTHOR: Allen A. Watson Manager, Systems Technology BERGEN EVENING RECORD 150 River Street Hackensack, NJ 07602 (201) 646-4111 ---------------------------------------------------------------- OVERVIEW: SRD is a directory manipulation utility written and maintained by DECUS members. It is available at no cost on the DECUS RSX SIG tapes. SRD uses a command line very much like PIP, just a bit simpler in most cases, since SRD is (deliberately) limited to doing directories and deleting files. The directories it produces look like the ones produced by PIP, with some minor format differences (some of which are user-selectable). This presentation centers on what makes SRD a useful program, with several examples of the directories it produces and suggestions for use, but does not provide either tutorial instructions on using SRD or full details on every capability of the program. MAIN MESSAGE: New users should try programs from the SIG tapes, starting with SRD, because: * SRD gives directory capabilities not included in PIP. * SRD is faster than PIP and uses less resources. * SRD has a compatible command-file generator program. * SRD is easy to install. * SRD is tested and safe. * SRD is free. 1.0 SRD capabilities not in PIP SRD has long had many capabilites in building directories that could not be duplicated by PIP. SRD has supported "partial" wildcard characters for years, for example, a filespec of "A*.MAC" would produce a directory of all files beginning with the letter SRD -- The DECUS Sort Directory Utility Page 2 "A" that have an extension of ".MAC". SRD has also supported selective directories by date. Both of these capabilities have been added to PIP in the latest release for RSX-11M Version 4.0 and RSX-11M-PLUS Version 2.0. SRD has continued to stay ahead of PIP, however, and still does many things PIP cannot do. These additional features continue to justify the inclusion of SRD as a supplemental directory program on RSX systems. 1.1 Sorting your directory The greatest single feature of SRD that distinguishes it from PIP is that it sorts your directory every time it displays it. The _____ ____ _________ standard sort order is ascending by file name, ascending by file type, and descending by version number. Below is a short directory sorted by SRD. ** DB5:[2,24] 10-OCT-82 15:57 ACNTRN .SYS;6 ACNTRN .SYS;5 BATCH .CMD;1 BATCHC .BAT;1 C .OLB;1 EDTINI .EDT;1 FDVLRM .OLB;1 FDVNEW .OLB;1 LOGIN .CMD;1 MAILBAG .TXT;1 MAILBOX .TXT;1 OPTION .C ;1 OPTION .CMD;1 RMSFMS11 .ODL;1 RMS11X .ODL;1 TMP .MAI;1 UFDS .CMD;1 UFDS .DIR;1 UFDS .LST;1 UFDS .TEC;1 UFDS .TES;1 17SEPACC .LST;1 21SEPACC .LST;1 22SEPACC .LST;1 23SEPACC .LST;1 SRD -- The DECUS Sort Directory Utility Page 3 1.1.1 Types of sorts - As stated above, the SIG-supported version of SRD supports a standard sort order by name, type and version. You can suppress sorting by a commandline switch. Another switch is provided to allow the sort order to be first by extension, then by name and version, as shown below: ** DB5:[2,24] 10-OCT-82 15:57 BATCHC .BAT;1 OPTION .C ;1 BATCH .CMD;1 LOGIN .CMD;1 OPTION .CMD;1 UFDS .CMD;1 UFDS .DIR;1 EDTINI .EDT;1 UFDS .LST;1 17SEPACC .LST;1 18SEPACC .LST;1 20SEPACC .LST;1 21SEPACC .LST;1 22SEPACC .LST;1 23SEPACC .LST;1 TMP .MAI;1 RMSFMS11 .ODL;1 RMS11X .ODL;1 C .OLB;1 FDVLRM .OLB;1 FDVNEW .OLB;1 ACNTRN .SYS;6 ACNTRN .SYS;5 UFDS .TEC;1 UFDS .TES;1 MAILBAG .TXT;1 MAILBOX .TXT;1 Other versions of SRD that have appeared on SIG tapes allow the sort order to be further altered -- the three sort fields can be specified in any order, and can be made to sort in either ascending or descending order. The version of SRD supported by the working group does not include these features; however, the interested user with some MACRO capability can locate them on older SIG tapes and implement them if he wishes. 1.1.2 Write-back sort - SRD also possesses the ability to write the sorted directory back to disk. Normally, each time it is run, SRD sorts the directory before displaying it on the terminal. With the addition of a /WB switch to the command line, SRD will also write the sorted SRD -- The DECUS Sort Directory Utility Page 4 directory back into UIC [0,0] (where directories are kept). This means that subsequent directories built using PIP will also display the directory in sorted format. Another way the write-back capability can be useful is to sort the directory of [0,0] itself and write it back. Then any directories done using wildcards as part of the UIC will display the directories in numeric sequence rather than in the random order in which the directories were originally created. Early versions of SRD had a bug in using write-back, and the documentation warned against using the feature unless a backup copy had first been made of the disk. This bug has been fixed. We at THE RECORD have been using write-back regularly for two years with not a single problem. 1.2 Extended selection criteria 1.2.1 By date and by time - Although PIP (and DCL DIR) in the latest releases have added the ability to select files by date and time, SRD still does it better, does more, and with a simpler syntax. It also does it faster (see timings given below). SRD provides five switches for date selection; DA to select files created on a given date (and time, optional), AF and AE to select files created after (or on or after) a given data (and time, optional), and BF and BE to select files created before (or on or before) a given date (and time, optional). In addition, SRD can select by creation date or by revision date. Our SRD is set up (at task build time) to select by revision date, so we use the /-RD switch to suppress this and select by creation date. Here are some examples: Commandline: SRD [2,24]/DA:24SEP82 -- files revised on 24-SEP-82 ** DB5:[2,24] 10-OCT-82 16:29 ACNTRN .SYS;6 24-SEP-82 12:57 (3.) ACNTRN .SYS;5 24-SEP-82 12:55 (3.) 17SEPACC .LST;1 24-SEP-82 12:58 18SEPACC .LST;1 24-SEP-82 12:59 20SEPACC .LST;1 24-SEP-82 12:59 21SEPACC .LST;1 24-SEP-82 13:00 22SEPACC .LST;1 24-SEP-82 13:01 23SEPACC .LST;1 24-SEP-82 13:01 SRD -- The DECUS Sort Directory Utility Page 5 Commandline: SRD [2,24]/DA:24SEP82/-RD -- files created on 24-SEP-82 ** DB5:[2,24] 10-OCT-82 16:29 17SEPACC .LST;1 24-SEP-82 12:58 18SEPACC .LST;1 24-SEP-82 12:59 20SEPACC .LST;1 24-SEP-82 12:59 21SEPACC .LST;1 24-SEP-82 13:00 22SEPACC .LST;1 24-SEP-82 13:00 23SEPACC .LST;1 24-SEP-82 13:01 Commandline: SRD [2,24]/AE:24SEP82 -- files revised on or after 24-SEP-82 ** DB5:[2,24] 10-OCT-82 16:30 ACNTRN .SYS;6 24-SEP-82 12:57 (3.) ACNTRN .SYS;5 24-SEP-82 12:55 (3.) MAILBAG .TXT;1 28-SEP-82 08:53 (2.) TMP .MAI;1 08-OCT-82 09:35 17SEPACC .LST;1 24-SEP-82 12:58 18SEPACC .LST;1 24-SEP-82 12:59 20SEPACC .LST;1 24-SEP-82 12:59 21SEPACC .LST;1 24-SEP-82 13:00 22SEPACC .LST;1 24-SEP-82 13:01 23SEPACC .LST;1 24-SEP-82 13:01 Commandline: SRD /AE:15:00 -- files revised today after 15:00 ** DB5:[2,32] 10-OCT-82 16:30 AE .DIR;1 10-OCT-82 16:30 DANA .DIR;1 10-OCT-82 16:29 DARD .DIR;1 10-OCT-82 16:29 EXT .DIR;1 10-OCT-82 15:57 NAME .DIR;1 10-OCT-82 15:57 SRDTALK .RNO;10 10-OCT-82 16:20 SRDTALK .RNO;7 10-OCT-82 16:09 SRDTALK .RNO;6 10-OCT-82 15:52 1.2.2 By version - SRD has three switches that select by version number: SV (select most recent versions), HV (higher version than), and OV (obsolete version). To me, the OV switch has proved most useful. 1.2.2.1 SV -- select most recent versions - SRD normally defaults to listing all versions of a file, as you may have noticed in the directories above. SRDTALK.RNO, for example, was listed three times in the last example. The SV switch allows you to specify a maximum number of versions to list. /SV by itself will list only the most recent version, as if you SRD -- The DECUS Sort Directory Utility Page 6 had typed "SRD SRDTALK.RNO;0". But you can ask for a number of most recent versions by appending the number to the switch. For example: Commandline: SRD S*.RNO/SV:2 -- list two versions of .RNO files starting with "S" ** DB5:[2,32] 10-OCT-82 16:50 SRDCMD .RNO;1 SRDTALK .RNO;11 SRDTALK .RNO;10 SWEEP .RNO;1 As you can see, if only one version exists that is all that is listed. 1.2.2.2 HV -- Higher versions - If you want to see all versions of files with a version number higher than "N" , you use the HV switch. You might, for example, use PIP to rename all files in a UIC to Version 100. Then, after extended editing of many files, you could use SRD /HV:100 to find all new versions created in the editing session. 1.2.2.3 OV -- Obsolete versions - An extremely useful switch. My main use is to give me a preview of what will be deleted if I do a purge. SRD /OV will list all files in a UIC for which a higher version exists. Thus, if I have a file called BYTE.ME in versions 1, 2 and 3, /OV will list only versions 1 and 2. These are the files that would be purged by a PIP BYTE.ME/PU or an SRD BYTE.ME/PU. It accepts a number, /OV:n, so that you can omit the "n" highest versions, corresponding to a /PU:n. I also use OV in combination with SD (selective delete) to step through the obsolete files and delete only certain ones. 1.2.3 By file condition - SRD also has switches that allow you to select files with a certain characteristic: contiguous, locked, multiheader, and zero length (the CO, LO, MU, and ZE switches). If you can't imagine a use for these switches you probably don't need them. We run a "locked file report" once a week and ask programmers to clean them up. SRD -- The DECUS Sort Directory Utility Page 7 1.2.4 By wildcards - SRD has long had extended wildcard support. In addition to the wildcard capabilities now in PIP (which I assume you are familiar with), SRD supports what is called implicit wildcarding and a second wildcard character that can be used to represent only a single character in a file specification. Implicit wildcarding is a feature that can be included or omitted at the time you task build SRD. Basically, it assumes wildcards even when you don't give them. This tends to shorten command lines and usually gives the desired result. For example, instead of typing "PIP S*.*;*" to get all files starting with "S" , with implicit wildcarding you just type "SRD S". To get a specific file called "S" you would have to suppress implicit wildcarding with an additional switch, e.g. "SRD S/-WI". (Note that any features selectable at task build time can be omitted or included by switch selection as you execute SRD.) Commandline: SRD S (with implicit wildcarding) ** DB5:[2,32] 10-OCT-82 17:17 -- S .TXT;1 SEARCH .TEC;1 SRDCMD .RNO;1 SRDTALK .RNO;13 SRDTALK .RNO;12 SRDTALK .RNO;11 SRDTALK .RNO;10 SRDTALK .RNO;7 SRDTALK .RNO;6 SRDTALK .RNO;5 SV .DIR;1 SWEEP .MEM;1 SWEEP .RNO;1 Commandline: SRD S (without implicit wildcarding) ** DB5:[2,32] 10-OCT-82 17:17 S .TXT;1 Even with implicit wildcarding suppressed, SRD will assume wildcards for portions of the file spec that are not given; above, the extension and version were omitted, so SRD looked for files as though we had typed "S.*;*" for the file spec. Finally, SRD supports a singleton wildcard character that represents only one character in a filespec. For example, here is a directory of files which have only two characters in their file name: SRD -- The DECUS Sort Directory Utility Page 8 Commandline: SRD %% ** DB5:[2,32] 10-OCT-82 17:29 AE .DIR;1 BC .DAT;1 SV .DIR;1 WI .DIR;1 1.2.5 Negation switch - SRD has a switch (/NE) that reverses the selection criteria specified. Thus, *.MAC/NE would list all files that are NOT of type MAC, etc. 1.3 Other capabilities of SRD In addition to displaying directories, SRD can also purge, delete, and selectively delete files. (It cannot copy.) All of the selection criteria above can be used in combination with these deletion switches, giving extremely powerful control to a system manager for maintaining his disks. 1.4 Output file in editable format Like PIP, SRD can send its output to a file instead of a terminal. Unlike PIP, the file produced is one that can be easily edited by standard text editors. PIP includes Carriage Returns and Line Feeds in a way that make for awkward editing; SRD does not. If you wish to use your directory program to produce files that will be edited into command files, this can be important. When the output of a multi-UFD directory is spooled to the printer, SRD will cause each UFD to be listed on a separate page. 1.5 Timings: SRD vs. PIP Even when compared to PIP in things both programs can do, SRD is still better because it is faster: up to four times faster. We modified the build command files to build a non-overlaid version of SRD, and it is this version I have timed; the overlaid version is probably somewhat slower, but still faster than PIP. (The non-overlaid build file will be in [333,100] on the Fall 82 SIG SRD -- The DECUS Sort Directory Utility Page 9 tape.) Using the task perfomance monitoring features of M-Plus Version 2.0, I arrived at the following timings for PIP and SRD doing identical directories: PIP SRD ----------------------------------- ELAPSED TIME 15s 3s CPU TIME 140 61 DIRECTIVE COUNT 481 101 QIO COUNT 204 56 TASK CONTEXT LOADS 196 65 In several stopwatch timings on a loaded system, doing a PIP /LI and an SRD /MI, I found the average time over five tries was 16.29 seconds for PIP and 4.11 seconds for SRD. Considering the number of times users build directories, this alone is enough reason to use SRD and to modify DCL so the DIR command uses it, too. On multi-UFD wildcard searches, SRD is even more dramatically faster. Here are some timings taken on a nearly quiescent system using PIP and SRD to search for all files beginning with "A" in group 2. A total of nnnn files had to be examined. Note that adding the SRD /SM switch (for summary line, similar to PIP's /TB) had nearly no effect. PIP SRD SRD /SM ----------------------------------------------- ELAPSED TIME 2:24 0:12 0:12 CPU TIME 1030 301 319 DIRECTIVE COUNT 4747 388 408 QIO COUNT 1646 198 218 TASK CONTEXT LOADS 1637 147 132 Here SRD shows itself to be twelve times faster than PIP! And ______ _____ ______ ____ ___ remember, SRD is also sorting the directory! The only thing in which PIP seemed to come close to SRD was in reporting total blocks for a group or in finding a specific file within a group consisting of several member UFD's. Even here, though the elapsed time was comparable, SRD did it either in less CPU time or with one fourth of the directives and about 30% of the QIO's. 2.0 Ease of installation The version of SRD supported by the working group is found in UIC [312,332] on the Spring 1982 RSX SIG tape. Many other versions exist on this and earlier tapes; the tape index provided is helpful for tracking down other versions if you want. SRD -- The DECUS Sort Directory Utility Page 10 The distribution kit includes a complete 17-page user manual and a HELP file that can be added to your system, all source code, and a build command file that fully prompts you concerning every option of SRD. The command file will build SRD for RSX-11M, RSX-11M-PLUS, RSX-11D and IAS. It can support FCSRES or FCSFSL if you have them, and knows about dynamic checkpointing. If you take a few minutes to read it over before you start you will be able to intelligently answer the questions it asks about desired options. It ran flawlessly for me. The features of SRD you can customize at build time include sort order, list by default, sort by default, use of revision date, inclusion of system accounts and [0,0] in wildcard searches, format of the middle size directory, and implicit wildcarding. 3.0 SRDCMD -- command file generator SRD has a compatible command-file generator called SRDCMD that can save you a lot of time. It is found in [330,4] on the Fall 81 RSX tape. Basically, SRDCMD is a program that generates command files. It accepts a command line just like SRD, followed by a template line for the command file to be generated and the name to be given to that file. When invoked, SRDCMD sub-tasks SRD to build a directory output file and then operates on that file to insert the file names into the template you have given. What can you do with SRDCMD? Well, just suppose you want to run MACRO assemblies of all the .MAC files you have created today. You could use this command line: CMD *.MAC/DA MAC 'N,'N/-SP=JOBPRE,'N >JOB.CMD SRDCMD will find all the .MAC files created today, insert the file name into the template wherever a 'N occurs, and write the results into a file called JOB.CMD. The results might look like this: MAC BACKW,BACKW/-SP=JOBPRE,BACKW MAC SAVBOTV2,SAVBOTV2/-SP=JOBPRE,SAVBOTV2 MAC TEST,TEST/-SP=JOBPRE,TEST The idea is you can use SRD's power to select files and in addition have the output automatically edited for you. I use SRDCMD frequently to generate PIP command files when the selection criteria I want don't exist in PIP; for example, deleting all zero length files, or copying files more selectively than PIP allows. SRD -- The DECUS Sort Directory Utility Page 11 4.0 SRD is tested and safe SRD has been in existence for many years and is in use on hundreds, perhaps thousands of systems. It was distributed by Digital on early RSX installation kits as unsupported software. You may even have an old version of it on your system and not know it; look when you get home! All of SRD's known bugs have been found and fixed. To my knowledge, the current version has no reported bugs. Unlike some untried programs that find their way onto the SIG tapes, I am as certain as one can be about software that it will in no way damage your system. SRD is maintained by a SIG working group and is being continually improved. Each new DECUS finds new features in SRD. Every time I think it has gone about as far as it can, someone comes up with something else useful for it to do, and sets about doing it. Dozens of expert programmers have worked on it over the years to make it not only useful, but safe and highly efficient. Details on latest enhancements to SRD for Fall, 1982 were not available at the time this document was prepared, but will be announced in the session. 5.0 SRD is free The final reason you ought to try SRD is, it's free. The most it can cost you is a media charge, and most local user groups distribute tape copies of the symposium tape for free. 6.0 SUMMARY I have emphasized that SRD gives you directory capabilities not included in PIP. SRD sorts your directory in two ways, and if you wish, writes it back to disk. You have many more selection criteria: time as well as date, using either revision or creation dates; you can select by most recent versions, obsolete versions, or versions above a certain number; you can select locked, contiguous, zero-length or multi-header files. SRD's wildcard capabilities are greater, including singleton wildcards. The output file is easier to edit than PIP's. SRD runs 4 to 12 times faster than PIP for most directory functions. SRD is easy to install, is tested and safe, and is maintained by a SIG working group. There is a compatible command file generator to go along SRD -- The DECUS Sort Directory Utility Page 12 with it, also on the SIG tapes. And best of all, it's free. Table of Contents 1.0 SRD capabilities not in PIP . . . . 1 1.1 Sorting your directory . . . . . . . 2 1.1.1 Types of sorts . . . . . . . . . . 3 1.1.2 Write-back sort . . . . . . . . . 3 1.2 Extended selection criteria . . . . 4 1.2.1 By date and by time . . . . . . . 4 1.2.2 By version . . . . . . . . . . . . 5 1.2.2.1 SV -- select most recent versions 5 1.2.2.2 HV -- Higher versions . . . . . 6 1.2.2.3 OV -- Obsolete versions . . . . 6 1.2.3 By file condition . . . . . . . . 6 1.2.4 By wildcards . . . . . . . . . . . 7 1.2.5 Negation switch . . . . . . . . . 8 1.3 Other capabilities of SRD . . . . . 8 1.4 Output file in editable format . . . 8 1.5 Timings: SRD vs. PIP . . . . . . . . 8 2.0 Ease of installation . . . . . . . . 9 3.0 SRDCMD -- command file generator . . 10 4.0 SRD is tested and safe . . . . . . . 11 5.0 SRD is free . . . . . . . . . . . . 11 6.0 SUMMARY . . . . . . . . . . . . . . 11