% VAX-11 Librarian V04-00`[0]uwvva5u2CommandsoExampleGenerals InvokingOLogicalsrRefusal[Revision\,Windows `u\ 1 GeneralsA TOOL is a VAX/VMS utility for managing files. Specifically, itA can be used to copy, move, rename, delete, edit, or printA several previously selected files. To invoke TOOL, simply typeA TOOL at the DCL prompt. The terminal screen will be splittedA into three windows respectively called []-window, Status window,A and Messages window. The first is made to display a list of allA available files in your default directory, each of which can be A marked for subsequent operations through a reverse-videoA highlighting bar. The second window gives you real-timeB information about the file list and the progress done by the A ongoing operation. The third window is chiefly intended forA displaying any kind of message generated by the System or by TOOL.A TOOL is a keystroke-driven utility, that is, you don't need toA type in lengthy english-like commands to get its services.A Simply, you just hit some specific key and TOOL will promptlyA execute the related function. So, for example, you just hitA "C" when you are ready to copy a group of files to another directory. Happy filing!ww}\ 1 InvokingB You can run TOOL by giving the command $ RUN TOOL. However, the B preferred method involves the definition of the "foreign DCL B command" TOOL. In short, you create a symbol known to DCL that B is interpreted like a command. This way, you ca n add parameters A and/or qualifiers to the command line. A parameter is anA argument to a command, while a qualifier usually specifies anA option. First, you should put in your LOGIN.COM the following line,/ $ TOOL :== $your_disk:[your_directory]TOOL.EXEB Then, after you re-run your LOGIN.COM, you simply type TOOL at B the DCL prompt to invoke the program. Furthermore, you can add A one or more of the 5 TOOL qualifiers. For example, you can type% $ TOOL /STAT  /SILENT /EXCLUDE=*.DIR* This command line says TOOL# o "Don't display any *.DIR files" o "Use a fast directory scan"% o "Display accounting info on exit" 2 ParametersA The command TOOL has no parameters at all. May be in the future. 2 Qualifiers/SILENT /SILENTB When the []-window is being updated, that is, when the directory B is being searched (command "."), a small window, labeled B "Reading Directory Information", is created to display the name B of each file found. Adding the qualifier /SILENT to the command B line causes TOOL not to create such window, thus speeding up the  directory scan./BRIEF /BRIEFB Normally, all system messages sent to the Messages window are B displayed in full. Facility, severity, identification and text B are all output. You would get the same if, after giving the DCL B command $ SET MESSAGE /FAC /SEV /IDENT /TEXT, you should try to ; delete a non-existing file. In this case, DCL would reply: %RMS-E-FNF, file not foundB If, instead, you $ SET MESSAGE /NOFAC /NOSEV /NOIDENT /TEXT, you + would get the following shortened message: File not foundB This is exactly what the qualifier /BRIEF is for. Adding this B qualifier to the command line causes all system messages sent to B the Messages window to be displayed in the brief form, which ( perhaps will look neater to most users./STAT /STATA This qualifier controls whether a brief summary of accountingA information for the TOOL session is displayed, including the following items: o Elapsed real time o Elapsed CPU time o Buffered I/O count o Direct I/O count o Number of page faults8 The above statistics are displayed upon exit from TOOL./INTRO /[NO]INTROA Before opening its three windows, TOOL outputs a sign-on messageA including authorship/version information and a disclaimer. ThisA message lasts 10 seconds or until you press any key. SpecifyingA /NO INTRO on the command line makes TOOL not to display this2 information. However, /INTRO is taken by default./CONFIRM /[NO]CONFIRMB Before actually performing any file operation, TOOL asks for the B user's confirmation. A little window is displayed with the B question "Are you sure...?" and the user must press "Y" (for B "Yes") or "N" (for "No") to continue. This feature, though B almost always desirable, can be disabled by adding /NOCONFIRM B to the command line . However, it is *strongly* recommended not B to use this qualifier (in the negated form) if you have a B tendency to heedlessness. REMEMBER: Deleted files *cannot* be B recovered, unless you have some wonderful utility for this B purpose (if you have one, send me a copy!). Avoid using this A qualifier, if you have no special reason why. However, /CONFIRM is taken by default./SINCE /SINCE=timeA Selects only those files dated after the specified time. You canA  specify time as an absolute time, a combination of absolute andA delta times, or as one of the following keywords: TODAY,A TOMORROW, or YESTERDAY. The TODAY keyword is *not* taken byA default like in the DCL command DIRECTORY. An absolute time mustA be entered in the format DD-MMM-YYYY:HH:MM:SS:CC. When one orA more fields are omitted, the system supplies default values. Here are some examples:. $ TOOL /SINCE=TODAY ! current time, $ TOOL /SINCE=12-JUL-1991:12 ! 12:00 noonA $ TOOL /SINCE=15-::30 ! 12:30 AM, 15th of current month0 $ TOOL /SINCE=15 ! 3:00 PM, todayA For complete information on specifying time values, see the VMS DCL Concepts Manual./BEFORE /BEFORE=timeA Selects only those files dated prior to the specified time. YouB can specify time as an absolute time, a combination of absolute A and delta times, or as one of the following keywords: TODAY,A TOMORROW, or YESTERDAY. The TODAY keyword is *not* taken byA default like in the DCL command DIRECTORY. An absolute time mustA be entered in the format DD-MMM-YYYY:HH:MM:SS:CC. When one orA more fields are omitted, the system supplies default values. Here are some examples:@ $ TOOL /BEFORE=YESTERDAY ! 24 hours before 00:00 o'clock- $ TOOL /BEFORE=17-FEB-1990:12 ! 12:00 noonB $ TOOL /BEFORE=15-::30 ! 12:30 AM, 15th of current month1 $ TOOL /BEFORE=15 ! 3:00 PM, todayA For c omplete information on specifying time values, see the VMS DCL Concepts Manual./INCLUDE /INCLUDE=file-specA File inclusion qualifier. Only those files matching file-specA will get listed in the []-window, at startup. If this qualifierA is missing, the file inclusion mask is taken as *.*;* (all filesA of any type, all versions) by default. Note that file-spec mayA NOT contain node and/or device and/or directory, or it will beA discarded without notification. Here are a couple of examples:9 $ TOOL /INC=[...] ! Wrong. Ignored and replaced by *.*;*< $ TOOL /INC=*.FOR ! Right. Implicitly, only latest versionsA Since there is no ambiguity, the qualifier's name may beA shortened at will. The file-spec argument may optionally be3 enclosed in parenthesis, as in /INCLUDE=(*.COM;-1)/EXCLUDE /EXCLUDE=file-specA File exclusion qualifier. Files matching this file-spec will NOTA get listed in the []-window at startup. If this qualifie r isA missing, the logical name TOOL$XMASK is searched for. If neitherA this is found, the default file exclusion mask is take asA *.JOU;* Keep in mind that this file-spec is not going to beA parsed by RMS. It instead is used by a string matching routineA that requires a filename to be FULLY covered by a combination ofA normal characters and wildcards. So, for example, if you need to- exclude all *.DIR files, you'll have to type $ TOOL /EXCLUDE=*.DIR;*A because th e file-version part of this file-spec is NOTA implicitly filled by the RMS. On the command line, theA qualifier's name may be shortened at will (a simple /E willA suffice!) and its argument may optionally be enclosed in! parenthesis, as in /EX=(*.COM;%)wwS\ 1 CommandsA This section describes the use of all TOOL commands andA functions. Generally, a TOOL command is issued by simply typingA some special character. In the follow ing, a caret sign (^) nextA to an uppercase character stands for the control key associatedA to that character. So, for example, ^W is obtained by typing aA "W" while holding down the CTRL key. The same combination may beA represented by CTRL/W. Some keypad keys are also used. The* extended keyboard is partially supported. 2 COMMANDSA The following is a quick reference to all TOOL commands, listedA in alphabetical order. See specific help topics for more details on each com mand.9 A "About" Display authorship/version info9 B "Bottom" Highlite bottom file (the last): C "Copy" Copy marked files to destination; D "Delete" Delete all marked files w/confirm< E "Edit" Edit each marked files, one by one: F "Find" Locate file by matching filespec= H "Help" Extended help, same as pressing PF29 I "Include" Inclusion file mask, user entry= J  "Jump" Locate file by entry #, same as "#"7 L "Logging" Toggle message logging on/off: M "Move" Move marked files to destination; N "New dir" New default directory, user entry< P "Print" Print all marked files, one by one8 Q "Quit" Quit TOOL, same as pressing ^Z8 R "Rename" Rename only the highlited file9 S "Select" Mark all listed files, one-shot7 T "Top" Highli te top file (the first); U "Unmark" Unmark all listed files, one-shot9 X "Exclude" Exclusion file mask, user entry; $ "Spawn" Create a subproc and attach to it> . "Update" Re-scan directory & update file list9 : "Parent" Set default to parent directory9 ! "Escape" Shell out, same as pressing "$": ? "Help" Display pop-up command reference> # "Number" Jump to file #, same as pr essing "G"9 - "Back" Set default to [-], same as ":"9 ^B "Broadcast" Broadcast messages to terminals: ^C "Break" Interrupt the on-going operation5 ^D "Directory" Create a new (sub)directory< ^I "Info" Display technical file information> ^P "Protect" Set protections for all marked files> ^R "Reverse" Reverse background/foreground colors= ^T "Stats" Display usual ^T process statistics7 ^U  "User" Invoke a user-defined command> ^W "Refresh" Redraw the screen (possibly trashed)9 ^Z "Exit" Exit TOOL, same as pressing "Q"; PF1 "Xtnd serv" Extended services (TOOL 2.0 only)/ PF2 "Xtnd help" VMS-like help on TOOL8 PF3 "Prev page" Same as PrevScreen (see below)8 PF4 "Next page" Same as NextScreen (see below)? Space "Toggle" Toggle mark on hilited file & advance> Enter "Enter" Takes an  action depending on context: Return "Action" Context-dependent, same as Enter3 Delete "Blank" Erase the Messages window8 UP "File up" Highlite previous file in list4 DOWN "File down" Highlite next file in list= PREV "Prev page" Walk file list backword by 10 files< NEXT "Next page" Walk file list forward by 10 files@ In addition, the following keys are active in the input window:8 ^A "Insert" Toggle insert/overstrike mod es8 ^E "Goto EOL" Move cursor to the end of line: ^H "Goto BOL" Move cursor to beginning of line9 ^J "Del word" Delete the previous (left) word= ^X "Del BOL" Delete from cursor to start of line 2 CopyingA To copy one or more files to another directory, simply mark theA desired files then press "C". You are asked for a destinationA path which may contain node and device specification. A filenameA is obviously not accepted. If you just !confirm the initialA content of the input window (the current directory), additionalA version of all marked files will be created. Thus, you can makeA a "spare" copy of a file by just hitting "C" followed by RETURN.A Assuming you are in the directory [MYDIR.DATA] and want to copyA some files to the subdirectory [.TODAY], you hit "C", then "Y"A to confirm the operation, then (in the Destination Path inputA window) you move back 1 character and insert (literally) .TODAYA follo "wed by RETURN...et voila'! To specify a different deviceA (disk), quickly move to the beginning of the input line byA pressing ^H and insert there the disk name with the necessaryA trailing colon, like in DUA0:[HISDIR]. Should you want to copyA files to a remote DECnet node, simply add the node specificationA before the device, with the usual trailing double-colon, like in@ HERVAX::DISK$USER:[SUSAN.LOVE.LETTERS] (DISK$USER is the disk). 2 DeletingA Deleting several files is# easier with TOOL. You examine theA directory contents in the []-window, then mark all unwantedA files with the spacebar (marks are displayed as asterisks nextA to filenames), then you press "D". At this time, you are askedA to confirm the *whole* operation, namely, the deletion of allA those files at once. See the Status-window while the deletionA is in progress. With TOOL you can OVERRIDE file protectionsA when deleting files, but this feature is only available $ when noA file is marked, that is, when deleting the "current" file. IfA the file is protected against deletion, TOOL attempts to modifyA the file's protection bits for the OWNER access class, afterA your confirmation. For this to work, needless to say, you mustA have write access to the file. However, even if a directoryA file is unprotected, you will not be able to delete it unlessA it is empty. Example: you have a subdirectory [.STUFF] whoseA physical counterp %art is the directory file STUFF.DIR;1. Now,A unless [.STUFF] is empty, you cannot delete STUFF.DIR;1 evenA if its protection has the D-bit (for "Delete") set for theA owner. What you get, instead, is the RMS error message "ACPA could not mark file for deletion". See also the TOOL help onA CTRL/I (at the topic Commands-Specials-TechInfo) and the VMS; help on commands DIRECTORY /PROTECTION and SET PROTECTION. 2 EditingA The editor is invoked by pressing "E". Ei &ther the EDT (DigitalA Standard Editor) or the TPU (best known as EVE, Extensible VaxA Editor) system routine is DIRECTLY called, without spawning anyA subprocess. If no file is marked, the "current file" (theA highlited one) is edited. If several files are marked in theA []-window, the editor will be invoked REPEATEDLY for EACH ofA them. Note that, when in the editor, the CTRL/Y key isA disabled, while CTRL/C, CTRL/T, and CTRL/W are made to workA as 'expected. When back in TOOL from the editor, the file list isA not updated, so the new version of a file will be visible theA next time you press "." (the key for the "Update" command).A Pay attention to the fact that if you call twice the editorA on a certain file without updating the file list, you mayA end up re-editing the initial version. For example, assumeA you have a file TODAY.DAT;1 and you call the editor. ExitingA the editor with EX creates a TO(DAY.DAT;2 that is not listedA in the []-window, at this time. If now you want to makeA additional edits to TODAY.DAT;2 you *must* update the file listA by pressing "." or you would otherwise edit TODAY.DAT;1A Since the EDT editor is somewhat idiosyncratic in its handlingA of exception conditions, in some *very unusual* circumstancesA you might experience an unexpected exit from TOOL. Should this? ever happen, please let me know the exact context of the fact. ) 2 MarkingA One of the outstanding features of TOOL is the possibility forA the user to "mark" files for the subsequent operations. CommandsA like Copy, Delete, and Move are made to operate only on markedA files. You toggle marks on/off by pressing the space-bar. WhenA a file is marked, an asterisk is displayed between size andA name. Note that pressing the space-bar also causes theA scrolling bar to advance downward, unless you are positionedA over the last f*ile of the list. Thus, to select a group of nA contiguously listed files you just have to press the space-bar nA times. Two handy commands are available to speed-up fileA marking. The command "S" ("Select") marks ALL listed files,A while the command "U" ("Unmark") unmarks them ALL. Of course,A you can exploit the "include" feature of TOOL for the purpose ofA selecting a particular group of files. For example, if you areA going to delete all files whose names cont +ain the substringA DATA, it is best to (1) issue the command "I" ("Include") andA specify *DATA*.*;*, then (2) select all files with the commandA "S" and finally (3) press "D" to delete them. This procedure isA safest and faster than marking all files one by one, especiallyA if the group involved is numerous. If no files are marked,A commands like Copy, Print, Move, and so on, operate on theA highlighted file only, namely, on the file displayed in reverse video i ,n the []-window. 2 MatchingB Matching filenames is involved in the use of the three B commands "I" ("Include") "X" ("Exclude"), and "F" ("Find"). The B first is used to enter the file specification according to B which TOOL decides what files are to be displayed in the A []-window. Since this filespec is processed by the file system,A it is not taken literally. If - for example - you specifyA *.*;-1, this will be interpreted as "any files whose versionA- number is one less than the latest one". See also the help onB the /INCLUDE qualifier. The Exclusion mask (see also the help A on the /EXCLUDE qualifier) determines what files, among thoseA complying with the Inclusion mask, are NOT to be displayed inA the []-window. You set this mask using the "X" command. Finally,A the "F" command lets you locate the file having a name thatA matches an additional mask. Assume you are looking for theA file whose name starts wi .th "S" and contains the lettersA "UF", and you have a very long list of files in yourA []-window, among which there is a file STUFF.DAT. Then, afterA you press "F" and enter (literally) S*UF*, the highliting@ bar will move to the file STUFF.DAT. Note that the filemask7 you enter here is interpreted like in the command "X".2 MovingB To move one or more files to another directory, simply markB the desired files then press "M". You are asked for a destina /tionB path which may NOT contain node NOR device specification.B A filename is obviously not accepted. If you just confirm theB initial content of the input window (the current directory),B all marked files will be given 1 as version number, and no moveB will take place. Assuming you are in the directory [MYDIR.DATA]B and want to move some files to the subdirectory [.TODAY], you hitB "M", then "Y" to confirm the operation, then (in theB Destination Path input 0window) you move back 1 character andB insert (literally) .TODAY followed by RETURN... et voila'! InB moving the "current" file, TOOL can override file protections.B This may be useful when you wish to move a (sub)directory file toB another (sub)directory, since *.DIR files are normally protectedB against deletion. Note that when you move a *.DIR file youB actually alter yor directory tree. Assume you have the following directory tree: +--[.GAMES] 1 | [PROGRAMS]--+ | +--[.DATA]A Now, after you move the file DATA.DIR;1 (which you find inA [PROGRAMS]) to the subdirectory [PROGRAMS.GAMES], your directory tree will look like this:' [PROGRAMS]-----[.GAMES]--------[.DATA] 2 PrintingB You can print files by pressing "P". After your confirm, allB marked files are directly sent to the mighty Job Controller.B No subprocess is spawned and files are not opened by TOOL.B Files get enq2ueued in the system default print queue SYS$PRINTB (logical name). To use another queue (possibly associated to aB different printer), you just have to define the logical nameB TOOL$PRINT (see related help). Print completion is not notified.B The message issued after each file is "printed" refers to theB success of enqueuing, not to the success of the print.B To print with non-default features (for example, with a: different /FORM) you will have to resort to 3 a subprocess. 2 RenamingC The Rename feature of TOOL is somewhat different from the C other file commands in that it always operate ONLY on the C highlighted file, that is, multiple Rename is not possible with C TOOL. After confirming the command, you are prompted to modify C the name of the file. Only a filename is allowed, here. You B cannot specify any node/device/directory, or the command willB not be executed. In renaming the "current" file, 4 TOOLC can override file protections. This may be useful when you wish C to rename a (sub)directory file, since *.DIR files are normally B protected against deletion. No renaming takes place if the new* filename entered is equal to the old one. 2 LoggingB The command "L" is used to toggle on/off the message-loggingB feature of TOOL, that is, its capability of keeping a record ofB all messages sent to the lower window. Initially, this featureB is disabled. Pressing "L" mak 5es TOOL open a new log file (namedB TOOL.LOG, unless otherwise defined by the logical name TOOL$LOG)B and start writing all messages also to this file. In the logB file, the time each message was issued is also displayed alongB with the message itself. Typical lines in the log file will# therefore look like the following:; [14:39:02.95] TOOL> Searching default directory [RESEARCH]# [14:39:02.99] TOOL> Wait please.... [14:39:03.98] %RMS-E-NMF, no more files foundB Givin 6g the L-command again when logging is already enabledB causes TOOL to close the log file and clearing the internalB switch previously set. Each time message logging is switchedB on, a NEW version of log file is created. Note that broadcastB messages (like "New mail on node..." and the process statistics- displayed by CTRL/T) will also get recorded. 2 BrowsingB You can browse through the file list in the []-window by usingB the up/down arrow-keys, PF3 and PF4. 7The arrows make theB highliting bar move by lines, while PF3/PF4 make the bar move byB "pages" (10 lines). If your keyboard has the "previous screen"B and "next screen" keys, they are treated the same as PF3 and PF4.B If the directory you're in contains hundreds of files (hugh!),B using PF3/PF4 may still be slow (and boring). In such a case,B you can speed-up operations using the command "Jump", activatedB by pressing "J" or "#". You are asked for an entry number, whereB the h 8ighliting bar will quickly be positioned after you give anB ENTER. Entry numbers are those listed in the first column in theB []-window,. Of course, if you enter an incorrect number (i.e.B negative or greater than the number of listed files), no action will be performed. 2 SpawningB The command "$" (alias for "!") is used to create a subprocessB which is then given control by attaching it to your terminal.B At this time, you can give whatever DCL command you need. WhenB y9ou are ready to re-enter TOOL, just type LOGOUT; you are thenB given the last chance to take a look at the screen contentB ("Hit RETURN when ready..."): after pressing RETURN you swingB back to the TOOL screen, with the same content it had when youB left it. Of course, the internal status of TOOL will also beB preserved (i.e., you won't have to re-select files previouslyB selected). Keep in mind that your subprocess will inherit theB same environment of the mast :er (the process running TOOL).B This means, by an example, that CTRL/T, CTRL/C and CTRL/Y willB be handled the same as they were before running TOOL. This isB because in the spawned subprocess, all the out-of-band AST6 trapping established in TOOL is temporarily disabled. 2 SpecialsB This section describes the purpose of commands activated by1 pressing ^B, ^D, ^I, ^R, ^P, ^T, ^W, and RETURN. 3 BroadcastA The special command ^B ("Broadcast") let you send messages t ;oA an interactive terminal. This is particularly useful when youA receive some broadcast message from another user and wish toA reply without leaving TOOL. Note that when you brodcast aA message to someone else's terminal, the message does notA interfere with any I/O operation (e.g. editing some text)A currently being performed by that user (*). To send a messageA in this fashion you have to know the identification of theA recipient's terminal, u<sually a short name like VTA223:A (note the trailing colon). This ID is usually part of anyA terminal-to-terminal broadcast message. After pressing CTRL/B,A you are first solicited to enter the message (initially set toA "Hello, there!"), then to specify the recipient terminal ID.A The initial string seen at this time is nothing but *your own*A terminal ID. You can test the ^B feature by simply pressingA CTRL/B and then twice: you will get "Hello, = there!"A in the Messages window. Actually, the message sent will take the following format:- From terminal XXXXX: - "Hello, there!"A Where means that an ASCII 7 character is prefixed (to ringA the recipient terminal bell), while XXXXX: is you own terminal identification.A IMPORTANT: unless TOOL is installed (with the standard VMSA utility INSTALL) with the OPER privilege, you will *not* beA able to broadcast messages to anyone but yourself, wh>ich is8 usually not very useful. (unless you are a neurotic :-) -----------------A (*) Technically speaking, the message is placed in a "mailbox". 3 A The RETURN (or ENTER) key is a somewhat special key in that itsA effect depends on the context. Here's a brief description of its functions:2 1. When hit on - say - JOHN.DIR, it has the same effect as the DCL command $ SET DEFAULT [.JOHN]2 2. When hit on - say - GAME.EXE, it has the same effect as the D?CL command $ RUN GAME5 3. When hit on - say - INSTALL.COM, it has the same effect as the DCL command $ @ INSTALL7 4. When hit on a file of type FILENAME.ABC, where ABC3 represents any file type not mentioned above, it) has the same effect as the DCL command $ some_command FILENAME1 where "some_command" is the translation of the1 logical name TOOL$IF_ABC, provided you defined3 one of this kind. So, for example, if you put in your LOGIN.COM @the line $ DEFINE TOOL$IF_LIS "EDT". then hitting ENTER on any *.LIS file in the2 []-window, will cause TOOL to invoke the editor- on that file through a spawned subprocess. 3 ReverseA You can reverse the background/foreground screen colors byA pressing ^R. With some terminals, this action improves theA readability. However, TOOL does not restore the screen's initial+ setting. Yes, this is another odd feature! 3 TechInfoA The command ^I (that is, CTRL/I ali Aas TAB) will pop up a windowA displaying some technical information about the file currentlyA highlited in the []-window (if any). Presently, eight pieces of information are given:1 1. The internal file Identifier, or FID. This is2 really made up of three numbers used by the file2 system to physically locate the file on the disk volume.5 2. The UIC (User Identification Code) of the owner,- in the format [group-id,member-id] like in1 [PHYSICS,HAWKING]. You cannot opeBrate on files/ owned by other users, unless those files are un-protected (see next item).5 3. The file protection settings. The format used to2 display protection bits is much similar to that3 used by the VMS command DIR /PROTECTION (see the4 related help), except that clear bits are visible as asterisks). Example:! (RWED,RWE,RE,) { DIR /PROT }" (RWED,RWE*,R*E*,****) { TOOL }2 4. The file's organization. It may be sequential,2 relative, indexed, or hashedC. Most of your files. are likely to be sequential. Your mail file, MAIL.MAI, should be indexed., 5. The attribute(s) of that file's records.0 Essentially, this specifies how each record is2 delimited. It may be Fortran-style, print-style,3 or carriage_return/line_feed. Or, it may be none.+ Whether records are allowed to span block boundaries is also reported.4 6. The format of each record in that file. They may/ be of fixed length, variable length, variable+ with fixed con Dtrol, one of three types of3 "stream", or even undefined. Most "normal" files2 are made of fixed length (executables, objects,3 directories) or variable length (typical of text files) records.* 7. The date & time that file was created.) 8. The date & time of its last revision. 3 SecurityB The special command ^P lets you set the file protection bitsB very quickly. This feature is kind of a "friendly" interface toB the DCL command SET PROTECTION (please refer to the re Elated VMSB help for details). In short, you can enable or disable the fourB different types of file access (read, write, execute, delete)B for the four different categories of users (system, owner, group,B world). After pressing CTRL/P, you are asked for the accessB class, then for the protection settings. Here, you toggle eachB bit on/off by pressing "R" for Read, "W" for Write, and so on.B When ready to perform the protection change for the desiredB files, you press FRETURN and the operation starts. Since theB operation is (almost) always reversible, there's no confirmationB box. However, disabling all kinds of access for the owner (you)B is not a recommended action; besides, it is foolish. Needless toB say, you will not be able to change any file's protection# settings if you are not the owner. 3 Refresh!A By pressing ^W you will get the TOOL screen refreshed, that is,A repainted according to the internal representation of it. This GA may be necessary when a "non-SMG" write operation happen to beA performed on the screen. While this is highly improbable, due toA TOOL's broadcast message asynchronous trapping, it might stillA occur in unusual circumstances. The refresh command is really aA "hot-key" in that it is active all the time, no matter whatA other operation is going on at the time you press CTRL/W. ForA example, you may refresh while entering an a nswer in a confirmation box. 3 StatisHtixA Normally, pressing ^T at any time cause a brief summary ofA process statistics to be broadcast to your terminal. In TOOL,A this is still the case. The only difference is that the statsA line is asynchronously trapped and rerouted to the proper placeA (the Messages window) instead of being output at an undueA position on the screen. The CTRL/T gives you eight pieces of information: 1. The local node name. 2. The name of your process. 3. The cIurrent system tyme.6 4. The name of the image currently being executed in your process.0 5. The cumulated CPU time used by the process. 6. The page fault count.3 7. The number of I/O operations (direct+buffered) performed by the process." 8. The physical memory occupied. 3 CreateDirA You can create new (sub)directories using the ^D ("Directory")A command. After pressing CTRL/D you are prompted to enter a validA directory specification. The initial string in the Jinput windowA is the current default directory. Assuming this latter isA [HERE], you just have to move left 1 character and type .DOWNA followed by RETURN to create the subdirectory [HERE.DOWN] whichA is then visible in the []-window as a file (DOWN.DIR;1) like anyA other. For this operation, you are not allowed to specifyA anything but a directory. Node, device, and (obviously!)A filename are not allowed. Note that if the specified directoryA already exist Ks, no new version is created. Multiple versions ofA a directory file should be avoided for the system to workA properly. If you have a directory with a version number otherA than 1, that is probably *not* really a directory and was surelyA *not* created by the RMS, that is, by using the normal $ CREATE /DIRECTORY. 2 WalkingA This section describes the use of commands used to walk aroundA directories. Essentially, you may "SET DEFAULT" to anywhere inA the dir Lectory tree by just using the ENTER key (alias RETURN) and ":" (alias "-").A If the file currently highlighted by the scrolling bar is aA directory (any *.DIR), then pressing ENTER will put you "inside"A that directory. So, for example, if the hilighting bar is uponA STUFF.DIR, hitting RETURN (alias for ENTER) will cause TOOL toA set default to [.STUFF]; this, in turn, will force TOOL to scanA that subdirectory of yours for any file matching theA Inclusion/E Mxclusion masks, eventually refreshing the StatusA window. Any time you hit RETURN on a *.DIR file, you will get a4 SET DEFAULT, thus walking down your directory tree.A To make steps backward, you just have to press ":" (dedicated toA UNIX people) or "-". This has the effect of setting default toA the parent directory, that is, to [-]. After hitting ":", youA will obviously get a new file list and an updated Status. IfA needed, setting default to a directory not list Ned in theA []-window involves the use of the "N" command ("New dir").A This will pop up an input window where the user is allowed toA enter a full directory specification with the usual, comfortableA line-editing (^X, ^J, ^E, ^H) and line-recalling (up/downA arrows). If the directory you specify does not exist, nothingA special happens, but TOOL won't obviously find any files, so youA will have to re-enter a new default directory by the same command ("N"). OA TOOL will always try to translate a directory specification,A so you don't have to remember the possibly long equivalence ofA "places" like SYS$LIBRARY or SYS$LOGIN. Furthermore, if youA prefix your directory specifier with a device name (like inA DUA0:[USERS.SCHULTZ]), the proper steps are taken to make theA whole thing work -- the logical name SYS$DISK is redefined accordingly.A Presently, network operations are only partially supportedA (you ma Py copy files to a remote DECnet node). In addition, youA cannot (obviously) set default to a concealed directory. GettingA the error message "Error in directory name" after pressing "-"A does not necessarily imply that the parent [-] directory doesA not exist, but, possibly, that [] is seen by your process as aA "root" directory. The same directory might be accessible through& another name. Ask you System Manager!ww@ \ 1 LogicalsA This section describes the usQe of some logical names that areA meaningful when using TOOL. These may be defined by the user inA order to change the path of certain TOOL-related files (such asA the TOOL help library file) or to modify the default actionA undertaken by TOOL while performing certain of its functions.A All logical names will be first searched for in the process'A logical name table, LNM$_PROCESS. If not found there, three moreA tables will be searched: LNM$_JOB, LNM$_GROUP, and LNM$_SY RSTEM.A Please refer to the VMS help on the DEFINE command for details on defining logical names. 2 TOOL$HELPA When you hit the PF2 key to get extended help, the system helpA library directory SYS$HELP is searched for the standard TOOLA help library file TOOL.HLB. If this file cannot be found there,A the logical name TOOL$HELP is searched for and - if found -A translated. You should therefore equate this name to a validA help library file located in a directory to w Shich you have readA access. In defining the logical name TOOL$HELP, you have toA specify a *complete* pathname, comprised of device, directory,A filename and extension. For example, you may wish to put in your( login script a line like the following:: $ DEFINE TOOL$HELP DISK$USERS:[JOHNSON.UTILITIES]TOOL.HLBA In this case, the standard TOOL help library file TOOL.HLB isA used. This file should be available on a system-wide basis,A though any other valid help file can Tbe used. If neither theA TOOL.HLB nor the user-specified help file can be found, noA extended help will be displayed, unless TOOL.HLB is located in the current default directory. 2 TOOL$PRINTA The logical name TOOL$PRINT affects the print queue used by TOOLA while printing files. At start-up time, if this name cannot beA found in any LNM table, the default print queue SYS$PRINT isA assumed. In defining TOOL$PRINT, keep in mind that this nameA must define a print U *queue*, NOT a device! So, for example, itA is *wrong* to define it as "LTA2:" or the like. File selectedA for print are not submitted through a spawned subprocess, butA directly sent to the Job Controller by means of a system service. 2 TOOL$LOGA When you turn on message logging with the command "L" (see theA related help) a new version of the "log file" is created. ThisA file, by default, is named TOOL.LOG and placed in SYS$LOGINA (your login directory), b Vut name and place can be redefined by9 using the logical name TOOL$LOG. Example: (in LOGIN.COM)+ $ DEFINE TOOL$LOG DISK$USERS:[SUSAN.TODAY]A Though the filespec defined by TOOL$LOG may include deviceA and/or directory, it MUST provide a filename, or it will be< ignored (without notification) and replaced by the default. 2 TOOL$IF_A This is a *very powerful* feature of TOOL in that it allows theA user to decide what action TOOL will perform on specified types; of file Ws. Assume you put in your login the following line: $ DEFINE TOOL$IF_FOR FORTRANA Then, each time you press RETURN (alias ENTER) on a file of typeA *.FOR, the FORTRAN compiler will be invoked - through a spawnedA subprocess, of course - on that file! There's obviously no limitA on the number of such TOOL$IF_* logicals you can define in your LOGIN (or elsewhere). 2 TOOL$XMASKA This logical name is searched for at start-up time. If found, itA is then translated to obtain an Exclu Xsion File Mask possibilyA different from the default one ("*.JOU*"). As all filenamesA listed in the []-window are comprised of name, extension, ANDA *version*, it is not effective to define TOOL$XMASK as "*.DIR"@ to exclude all directory files form listing. You have to equate6 TOOL$XMASK to the string "*.DIR;*" or simply "*.DIR*" 2 TOOL$EDITA Depending on the string equated to the logical name TOOL$EDIT,A either the EDT editor or the TPU editor is invoked for eachA Y marked file. If this logical name does not equate "EDT" orA "TPU", no other editor will be available through the commandA "E". If it is NOT defined, however, the editor defaults to EDT.B Typically, you will want to define your TOOL editor in your 9 LOGIN.COM script, by adding a line like the following: $ DEFINE TOOL$EDIT EDT 2 TOOL$USERA This logical name, if defined, specifies the command TOOL passesA to DCL when the "User" key (^U) is pressed. This command musZtA NOT be prefixed by the dollar sign ($) and may be a nything atA all. No argument is appended to this command. This feature isA much like the "Spawn" command, except that it doesn't requireA you to type in the command at the DCL prompt nor to type LOGOUT5 to return inside TOOL. Examples: (in your LOGIN.COM) $ DEFINE TOOL$USER "SWING"& $ DEFINE TOOL$USER "PURGE /LOG *.DAT"% $ DEFINE TOOL$USER "SET HOST NASA::"A If no such logical name is found in any of the sear [ched LNMA tables, no action takes place. On the other hand, If the command5 defined is invalid, all you get is an error message.2 TOOL$HELP_FRAMEB This logical name affects the way TOOL displays its help text. A If TOOL$HELP_FRAME is defined, no matter how, the help textA will be output in a full-screen framed window labeled "Help".A Otherwise, the text will come out in the usual (quicker)A fashion, namely, the one used by the VMS HELP. Yes, this is an odd fe\ature!ww\ 1 Revision  Version: TOOL 1.0 (beta) Revised: 18-JUL-1991A This is the first release, beta version, of TOOL. Please reportA any bug to the author at the address below. Any comment and/or' criticism will be greatly appreciated. Adriano Santoni, Dr.2 Istituto di Ricerche Farmacologiche "Mario Negri"( Unita' di Biomatematica e Biostatistica Via Eritrea, 62 20143 I-MILANO tel +39-2-39014446 fax +39-2-35462776 e-mail SANTONI@IMIMNV ]X.IRFMN.MNEGRI.IT (Internet)wwM\ 1 WindowsA This section describes purpose and features of all windows.A TOOL supports virtually *any* screen size. Try setting yourA terminal to 132 columns ($ SET TERMINAL /WIDTH=132) and seeA the changes! While the Status window has fixed dimensions,A the []-window becomes 100 columns wide, and files with veryA long names get listed in a more readable fashion. Furthermore,A if your terminal is really ^a DECwindows (tm) DECterm - or theA like - you will also be able to modify its height, namely, theA number of rows displayed. This will cause the Messages windowA to expand, too, so allowing the user to see more of the messageA "history". However, if the screen size is smaller than 24 rows xA 80 columns, TOOL will abort with an error message; after all,A there's no reason why you should shrink it. Note that TOOL isB not supposed to work properly with a screen size t _hat is A not really supported. For example, if you $ SET TERM /WIDTH=150A but your terminal can NOT really display 150 columns, TOOL willA behave strangely. Most likely, TOOL will `get confused' aboutA size and locations of its windows on the screen. Better to limit@ oneself to the traditional screen widths of 80 and 132 columns. 2 DirectoryA This is by far the most important window in TOOL. Here, allA files whose name comply with the Inclusion/Exclusion masksA are lis `ted along with their entry number and size. If theA filename does not fit in the window, the exceeding charactersA are not visible, but a diamond is displayed in the rightmost4 column. The following is a couple of typical lines:7 +----------------------------------------------------+7 |0023 170 * TODAY_RESULTS.DAT;5 |7 |0024 64 OLD.DATA;3 |7 +----------------------------------------------------+6 E S M N a D; E - Entry number (0-padded), currently limited to 1000.; S - Blocks (512 bytes) allocated to file. Right-justified.; M - Mark. Toggle on/off with the space-bar, "S", and "U".; N - Name. If too long, a diamond appears at position D.B This window is constantly labeled with the default directoryB name, unless too long to fit in 48 columns. Note that when TOOLB starts updating the list, the label is temporarily changed toB [], whence the bshortname of []-window. If no files are found inB the current directory, the window is simply blanked. Since onlyB 5 digits are available for the file size, it may happen - for2 very large files - that this field is overflowed. 2 MessagesB The lower window, labeled "Messages", is where TOOL writesB phrases describing what is going to be performed and the resultB of that operation. Most of the times, the result of an operationB (like the deletion of a file) is reported thro cugh the systemB message associated to the "condition value" returned by a systemB routine. To see how this works, try to delete a non-existingB file (example below): you will get a series of error messages.B The condition value associated to the first of them isB automatically saved in the DCL variable $STATUS for subsequent inspection. Experiment! $ delete NOSUCH.FILE;1; %DELETE-W-SEARCHFAIL, error searching for ...NOSUCH.FILE;1 -RMS-E-FNF, file not found $ d show symbol $STATUS $ $STATUS == "%X10931238" $ exit %X931238. %DELETE-W-SEARCHFAIL, error searching for !ASA Note that when a message is generated by TOOL, it is alwaysA prefixed by "TOOL>". System messages, instead, are alwaysA prefixed by the percent sign "%", unless TOOL was invoked withA the /BRIEF qualifier (see the related help), and displayed inA boldface, high-intensity, or in a different color (depending onA the terminal you have). See also the VMS help o en topic Lexicals, subtopic F$MESSAGE. 2 ConfirmB The confirmation window appears in many instances; for example,B before exiting TOOL and before a deletion is actually performed.B Here, you are expected to press "Y" (Yes) to confirm or "N" (No)B to deny, no matter the case. Pressing any other character (apartB from some hot-keys like ^W and ^T) will only cause a warning bell to ring.2 Status8 This window displays 12 important items of information:0 1. The "device" part of the fdefault directory.1 If your default is SYS$MANAGER:[SUPERMAN], the3 device name is SYS$MANAGER which is likely to be1 a logical name rather than a "true" (physical)2 name. This means that while SYS$MANAGER is seen1 as a device (say, a disk), its translation may1 well be a subdirectory. You can verify this by1 typing SHOW LOG SYS$MANAGER at the DCL prompt.5 2. The name of the physical device where your files4 actually reside. This field may be similar to the2 prece gding one (example: Device name "DUB2:" and2 Physical name "_DUB2:"). If the logical name of4 the example above, SYS$MANAGER, translates to the1 subdirectory DUA0:[SYS0.SYSCOMMON.SYSMGR], the! physical device name is _DUA0:6 3. The total number of blocks (512 bytes each), both0 allocated and free, available on that device.6 4. The total number of free blocks remaining on that4 device, namely, the amount of free space on disk.3 You will see this number change dynamically whhen copying or deleting files.6 5. The file inclusion mask, wich you may change with2 the command "I". This is the file specification3 used in searching the default directory. Related& help at the topic Command Matching.5 6. The file exclusion mask. File matching this mask3 are NOT listed in the []-window. See the related" help (topic Commands Matching).6 7. The total number of files listed in the []-window4 8. The total number of files that you have marked,0 i both as an absolute number and as percentage.1 Marks are displayed as asterisks ("*") and can3 be toggled on/off with the space bar. Operations4 like Copy ("C"), Delete ("D"), or ("Move") affect only marked files, if any.5 9. The total number of blocks (512 bytes) allocated4 to all listed files, that is, the disk space used2 by those files. Note that the size of each file0 is also listed in the []-window (2nd column).2 10. The number of blocks allocated to all marked j+ files, both as an absolute number and as! percentage of the above total.4 11. The number of successful operations performed.+ This field is only reset when a new file/ operation is started. Example: if you marked0 10 files for deletion and 2 of them could not/ be deleted, you'll see 8 in this field. When1 the deletion is in progress, the success count1 is incremented after the file being acted upon has been properly processed.0 12. The number of failed ope krations performed.+ This field is only reset when a new file/ operation is started. Example: if you marked, 10 files for copy and 3 of them could not. be copied, you'll see 3 in this field. When. the copy is in progress, the error count is. incremented after the file being acted upon# has NOT been properly processed.2 InputA An input window appears whenever TOOL needs some informationB from you. This window has full width (the terminal's) but only B few lines. Onlyl the upper part of the border, showing the title, B should normally be visible. In many cases, this window contains B an initial string which is treated as a "default" input from B you. This default will usually be set according to a B convenience criterion. For example, the Destination Path for A the Copy ("C") command will be initialized to the currentA default directory. This way, if you intend to copy some file(s)A to a subdirectory, you may limit yoursel mf to modify thatA directory specification, instead of re-entering it in full.A Suppose you are in some directory of yours, sayA [SYSMGR.GARBAGE.UNIX], and wish to copy (or move) some file(s)A to the subdirectory [-.TOPS] Then, after marking (see relatedA help) the desired files, you press "C" (or "M" to move). AtA this time, you find yourself in an input window labeledA "Destination Path" with the initial content [GARBAGE.UNIX]A You can n now simply modify this initial directory specificationA by making a step backward with the left-arrow and enteringA (literally) -.TOPS Note that while in the input window, youA can use line-editing control-keys like those described in theA VMS help at the topic "Line_editing". TOOL saves and allows youA to access up to 20 of your most recently entered strings. You8 can recall them one by one by using the up/down arrows. Editing key Function performed -----------o ------------------; CTRL/H, F12 Moves the cursor to the beginning of the line.8 CTRL/J, F13 Deletes the word at the left of the cursor.> CTRL/A, F14 Switches between overstrike mode and insert mode.1 CTRL/E Moves the cursor to the end of the line.9 CTRL/X Deletes from beginning of line up to the cursor.A There's a limitation, however, that is worth mentioning. You canA NOT enter more than 80 characters in the input window; the 80thA characters is taken as a "terminator" by p TOOL, namely, it isA followed by an implicit carriage-return. You may ask yourself:A "Why is the input window 4 lines high if I cannot enter more: than 1 line?". The answer to this question is: "Because."ww ] 1 Example@ The following is a sample set of definitions to be put in@ your LOGIN.COM, namely, the DCL script first executed when loggin in to the system.* $! Create the "foreign DCL command" TOOL.+ $! This way, you just have to type TOOL tqo* $! run it. Otherwise, you'll have to type+ $! RUN TOOL thereby losing the possibility, $! of appending qualifiers like /INCLUDE to' $! the command line. Here, TOOL.EXE is' $! assumed to be located in your root.. $! If this is not the case, replace SYS$LOGIN $! with the proper path. $!! $ TOOL == "$ SYS$LOGIN:TOOL.EXE" $!$ $! Define the location of the help( $! library database (press "H" or PF2) $!* $ DEFINE TOOL$HELP SYS$LOGIN:TOOL.HLB $!+ $! Define your preferrred editor to be used+ $! from inside TOOL. Either "EDT" or "TPU"( $! is required, or no editor will work. $!& $ DEFINE TOOL$EDIT EDT ! Mandatory $!) $! Define the command TOOL passes to DCL* $! when CTRL/U is pressed. Avoid dollars. $! $ DEFINE TOOL$USER SWING $!- $! Define the full pathname of the log file,, $! where all messages will be written after, $! you enable logging with the "L" command.+ $! Since no device/directory is specified,. $! the file will go in thse current directory. $!# $ DEFINE TOOL$LOG TOOL_LOG.LIS $!& $! Define the command invoked by TOOL* $! when the RETURN key is pressed and the& $! highliting bar is on a *.DOC file. $!" $ DEFINE TOOL$IF_DOC "TYPE/PAGE"ww0] 1 Refusal= The author has made his best efforts in producing TOOL, but:@ THE SOFTWARE DESCRIBED IN THIS DOCUMENT IS PROVIDED "AS IS" AND@ NO GUARANTEE IS MADE BY THE AUTHOR AS TO THE SUITABILITY,@ RELIABILITY, SECURITY, USEFULNEtSS, OR PERFORMANCE OF THIS SOFTWARE.@ THIS SOFTWARE IS IN THE PUBLIC DOMAIN AND MAY BE FREELY@ DISTRIBUTED WITHOUT CHARGE AS REQUIRED. HOWEVER, ALL COPYRIGHT@ NOTICES AND REFERENCES TO THE AUTHOR IN THE SOURCE MUST BE LEFT INTACT.@ THIRD PARTY MODIFICATIONS MAY BE MADE TO THE SOURCE BUT ANY@ ERRORS ARISING FROM THEIR USE ARE ENTIRELY THE RESPONSIBILITY OF THE MODIFIER.@ If you find TOOL easy, fast, and convenient to use, a small@ contribute from you, to be se unt at the address stated below,@ would be appreciated. The amount of such contribution is up@ to you. Just consider the effort of planning, developing and@ debugging such a program, and the value it has (if any) to you.* *-----------------** | Adriano Santoni |* | via Carducci, 8 |* | 20035 Lissone |* | (Milano) ITALY |* *-----------------*A I am much indebted to Dr. Massimo Vitali, System Manager here atB the IRFMN Institute. He has taught me lots of things and I would B hardly have developed this program without his friendly support. ww]`K] SANTONI GeneralsInvokingCommandsLogicalsRevisionWindowsExampleRefusal