E  DFIND - A program to assign logical names to a wildcarded file spec. 6  COPYRIGHT (C) 1993, 1994, 1995        Erik Ahlefeldt.  VERSION 2.0  	  SUMMARY.   -------  P  Dfind is a program that assigns short logical names to a wildcarded file speci-L  fication. These logical names can then be used in all DCL commands, therebyH  saving you a lot of typing.  It serves as a partial replacement for theH  DIRECTORY command and can greatly reduce (or eliminate) the need to SETN  DEFAULT to different directories. At the sites that have tried this utility, P  it has become as indispensable as the command recall facility. You will wonder +  how you ever managed without it. Trust me.     	  Example. E      $ D :== $DEV:[DIR]DFIND/PREFIX=D   ! in login.com or sys$sylogin        $ D DISK1:[U*.S*]*WIDGETS.*  ,      D1:  DISK1:[USERGROUP.SANTA]WIDGETS.COM0      D2:  DISK1:[USERGROUP.SANTA]SET_WIDGETS.COM2      D3:  DISK1:[USERGROUP.SANTA]UNSET_WIDGETS.COM5      D5:  DISK1:[USERGROUP.SHORTHORN]BASS_WIDGETS.EXE 7      D5:  DISK1:[USERGROUP.SHORTHORN]DELETE_WIDGETS.COM 0      D6:  DISK1:[USERGROUP.SHORTHORN]WIDGETS.COM         I      $ EDIT D1                  ! edit DISK1:[USERGROUP.SANTA]WIDGETS.COM I      $ COPY D1 D6               ! copy DISK1:[USERGROUP.SANTA]WIDGETS.COM M      $ DELETE D1:;*             ! delete DISK1:[USERGROUP.SANTA]WIDGETS.COM;* ?      $ D                        ! redisplay D logicals (if any)   ,      D1:  DISK1:[USERGROUP.SANTA]WIDGETS.COM0      D2:  DISK1:[USERGROUP.SANTA]SET_WIDGETS.COM2      D3:  DISK1:[USERGROUP.SANTA]UNSET_WIDGETS.COM5      D5:  DISK1:[USERGROUP.SHORTHORN]BASS_WIDGETS.COM 7      D5:  DISK1:[USERGROUP.SHORTHORN]DELETE_WIDGETS.COM 0      D6:  DISK1:[USERGROUP.SHORTHORN]WIDGETS.COM  L      $ DIR /DATE/SIZE=ALL D2:;-1           ! dir of previous version of file  &      Directory DISK1:[USERGROUP.SANTA]  C      SET_WIDGETS.COM;3           3/8        12-DEC-1993 10:42:33.07   !      Total of 1 file, 3/8 blocks.   C      $ SET FILE D4/PROT=W:E                ! set protection on file I      $ D *.COB                             ! set up new "D" list of cobol J                                            ! programs in default directory6      D1:  DISK17:[PROGRAMMERS.BRUCE]CONVERT_EBCDIC.COB1      D2:  DISK17:[PROGRAMMERS.BRUCE]INVOICING.COB 2      D3:  DISK17:[PROGRAMMERS.BRUCE]MAKE_SPIKE.COB       USAGE AND INSTALLATION.  ----------------------  O Dfind is designed to be run as a DCL foreign command. I would suggest including N it in the systemwide login file (usually pointed to by the SYS$SYLOGIN logicalN name), otherwise put it in your own LOGIN.COM. Unzip the distribution set in aM safe place, and put the the file DFIND.EXE (VAX) or DFIND.EXE_AXP (Alpha) in  O the directory where you keep third-party or DECUS utilities and set protection  N on this file to be "W:E" or "W:RE". (If installing an an Alpha you may want to# rename DFIND.EXE_AXP to DFIND.EXE). K Typically you would set up a number of foreign comands in SYS$SYLOGIN file  # with different prefixes as follows:     $ A :== $DEV:[DIR]DFIND/PREFIX=A  $ B :== $DEV:[DIR]DFIND/PREFIX=B  $ C :== $DEV:[DIR]DFIND/PREFIX=C  $ D :== $DEV:[DIR]DFIND/PREFIX=D) $ DAP :== $DEV:[DIR]DFIND/PREFIX=D/APPEND   E This will allow a user to have four separate lists on the go at once. 3 Then to use Dfind with, for example, prefix B, type   & $ B [file-specification] [qualifiers]   J Dfind, where possible, works in a similar way to the DIRECTORY command. SoL Read access is required to the directory to obtain the name of a file; Read J access to the files is required to obtain information other than the file * name e.g. if using the "/SINCE" qualifier.  L An execution of Dfind without a file specification will display the previousG logical name list for that prefix. If there is no previous list it will J do nothing. Some qualifiers are mutually exclusive, therefore I have takenL arbitrary decisions (sensible I hope) about which qualifiers take precedenceI over which others. If you give Dfind a file specification without version I numbers it will assign logical names to files without version numbers; if P you give Dfind a file specification with version numbers it will assign logical M names to files with version numbers. Try "$ D *.COM" and "$ D *.COM;*" to see  the difference. K Logical names are defined by default in the LNM$PROCESS table, you can also I define them in other logical name tables, privilege permitting, by use of  the /TABLE qualifier.    QUALIFIERS. 
 ----------  K /APPEND   - appends new logical names to the existing logical name list for O             this prefix. e.g. if you have previously done a D command which set L             up D1, D2 and D3, this execution of D will set up D4, D5 etc andL             display the list from D4 onwards. (Use the D command without any=             qualifiers to display the whole list from D1 on.) *             Example.  "$ D L*.OBJ /APPEND"  P /BACKUP   - select files by backup date, used with /BEFORE and /SINCE qualifiersL             The effect of this qualifier is similar to the /BACKUP qualifier'             with the DIRECTORY command. B             Example.  "$ D L*.OBJ,L*.EXE /BACKUP /SINCE=YESTERDAY"  8 /BEFORE   - select files before specified date and time.O             Example.  "$ D DSK1:[PROGRAMS.*.EXE]RHINO*.EXE /BEFORE=01-APR-1993"   8 /CREATED  - creation date, used with /BEFORE and /SINCE.>             Example.  "$ D /CREATED /SINCE=YESTERDAY NET*.LOG"  O /DELETE   - deletes logical name list only, NOT the files associated with those L             logical names. In practice this is rarely used since the defaultJ             behaviour of Dfind is to delete the previous logical name listM             before assigning new logicals. However, if you ran out of dynamic N             memory on a previous execution of Dfind because you were trying toN             define a sqillion logicals, you may need to deassign those logicalM             names with the "/DELETE" qualifier to free up some dynamic memory C             for your process before attempting to do anything else. #             Example.  "$ D /DELETE"   5 /EXPIRED  - expiry date, used with /BEFORE and /SINCE J             Example.  "$ D /EXPIRED /BEFORE=02-APR-1993 SYS$SCRATCH:*.DAT"  - /HELP     - display a very brief Help screen. !             Example.  "$ D /HELP"   I /MAXIMUM  - maximum number of logical names to define (default 120). Once N             Dfind hits this limit it will skip defining any more logical namesM             and print an informational message. On any system there is going  N             to be a limit on how many logical names you can define before you P             run out of dynamic memory or some process quota.In practice you willN             find that more than 20 or 40 logicals in a single Dfind list gets M             unwieldy. You may increase this number up to 11111 as of version  K             2.0 of Dfind but you will likely run out of dynamic memory long ;             before you get that many logical names defined. 2             Example.  "$ D SYS$LOGIN:*.* /MAX=500"M                       "$ D SYS$LOGIN:*.* /MAX=15"  - stop at 15 logical names   8 /MODIFIED - modified date, used with /BEFORE and /SINCE.N             Example.  "$ D /MODIFIED /SINCE DATABASE$:*.DAT"  - modified today  N /PREFIX   - nominate a prefix (up to 3 characters) for logical names. I preferL             the shortest prefixes because the whole idea of Dfind is to saveI             typing long file specs. However you can define prefixes up to J             3 characters long. Prefixes of more than 3 characters will be              truncated.P             Example.  "$ D EARTH::L*.*;* /PREFIX=XYZ"   - change default prefix   7 /SINCE    - select files since specified date and time. G             Example.  "$ D/SINCE=YESTERDAY-2-00:00 L*.*;* /PREFIX=XYZ"    H /TABLE    - select logical name table to use, the default is the processK             logical name table LNM$PROCESS. You can define a Dfind logical  I             name list in any existing logical name table if you have the  J             privilege to do so. Beware of running out of JTQUOTA if using              the LNM$JOB table.P             Example.  "$ D DSK2:[PRGMR.BRUCE...]FIND.C /PREFIX=JJ/TABLE=LNM$JOB"                                 FUTURE ENHANCEMENTS.   --------------------      Fix file-spec "stickiness" bug.:  Add an /EXCLUDE qualifier when I figure out how to do it.  Improve error handling.6  Rewrite the file attribute retrieval subroutine in C.  Create a proper Help file.   
  CAUTIONS.
  ---------   O  Dfind defines short logical names of the form Xnn. If your site or application L  uses similar logical names for whatever purpose, be aware that use of DfindK  can overwrite existing logical names. You should therefore choose prefixes J  with care and allocate these for creation only by Dfind. Some third partyB  software, the Powerhouse 4GL for example, does symbol translationJ  when interpreting the name of a program to be run etc. If you have set upI  Dfind with "$ A :=== $dev:[dir]dfind/prefix=A" and you write a temporary E  Powerhouse program called A.QZS, when you tell Powerhouse to use the J  program "A" it will translate the symbol A and tell you that Dfind is not  a valid Powerhouse program!J  Dfind is not a privileged image, and does not give a user the power to doI  anything that he or she does not already have privilege to do. If a user I  does something foolish or disastrous with Dfind, they could have done it   just as well without Dfind.    MISCELLANEOUS.   -------------  L  Dfind source code consists of the main Cobol program  DFIND.COB , a FortranM  subroutine FILE_ATT.FOR which gets file attributes, a Macro stub EXTDEF.MAR  K  which gets hold of external definitions which Cobol cannot, and a CLD file F  DFINDCLD.CLD. A crude command procedure to build Dfind is supplied asK  MAKE_DFIND.COM. Version 2.0 of Dfind has been built on VAX using VMS 5.5-1 J  and COBOL 4.3 and on ALPHA using VMS 6.1 and COBOL 2.1. The Alpha versionJ  will probably not run on a version earlier than 6.1, so you will need to O  build or VEST your own version for the Alpha if you do not have V6.1 or later.     DISCLAIMER.  ---------- J  This program is supplied without warranty of any kind, either express or O  implied.  See file $GNU_GENERAL_PUBLIC_LICENSE.TXT supplied with this program    for full details.      COPYRIGHT.   ---------     N  All the source code for Dfind is original and was written by Erik Ahlefeldt, N  with the exception of the FILE_ATT subroutine which was adapted from a freelyP  available DECUS program (see FILE_ATT.FOR source for acknowledgement). No claimL  is made as to the copyright disposition of the FILE_ATT subroutine, BUT allL  other code is copyright of the author. The author retains the copyright of J  this program and it is made available for use under the terms of the GNU J  GENERAL PUBLIC SOFTWARE LICENSE. See file $GNU_GENERAL_PUBLIC_LICENSE.TXT0  supplied with this program for further details.         BUGS.  ---- K  When invoking Dfind with multiple file-specifications on the command line, O  the device-directory spec is not "sticky" as it is with the directory command. '  This will be fixed in a later release. M  Some obscure error conditions may still do a display of the kind "**** ERROR J  IN CALL TO LIB$..." because I haven't got around to cleaning up the error
  handling.N  No other known bugs at this stage (they're all undocumented features), BUT asO  mentioned above the error handling is not perfect (to say the least!). I have  O  been playing with this program for over ten years and I figured it was better  L  to get it out as is, rather than spend another ten years cleaning it up. I N  will look at any serious bug reports you care to send, when I have the time. P  My email address (August 1995) is "oahlefel@metz.une.edu.au"    Erik Ahlefeldt.  