Trailing-Edge - PDP-10 Archives - integ_tools_tops20_v7_30-apr-86_dumper - tools/rev/rev.doc
There are 3 other files named rev.doc in the archive. Click here to see a list.
			REV v3.5

	1.0 Executive Summary
	2.0 Invocation
	3.0 Commands
	    3.1 Deleting a subdirectory
	4.0 The User Selection Procedure Facility
	5.0 Installation

1.0 Executive Summary.
	REV is a file utility for REViewing a group of files.  It is based 
(loosely) around the TOPS-20 utility of the same name, but this one is, of 
course, based around the VAX/VMS file handling operations.  The utility 
walks through a group of files specified by the user (default *.*;*) and 
gives the user the opportunity to perform various operations on each file.

	Please note that REV is being tweaked frequently.  Inconsistancies 
may be ironed out in later versions.  Suggestions are welcome via MAIL to 

2.0 Invocation.
	To invoke REV, it is worthwhile to set up a symbol (e.g. in your 
LOGIN.COM file) by:-

 $ REV:==@[directory_where_REV_lives]REV

By doing this you can start REV just by typing REV regardless of your 
current default directory.  If no filespec is given in the invocation 
command, the current default device and directory is used with *.*;* , but 
you may specify any directory/file specification you require, for example:-


	Once running, REV shows you each file in the group you have 
specified and waits for you to tell it what to do about the file.  What it 
shows you is the file name, its size in blocks, and its creation date and 
time.  If you don't want to do anything to the file its is currently 
showing you (the 'current file'), just press <RETURN> to step on to the next 
file in the list.  There are, however, several operations you may wish to 
subject the file to while it is current.  The options available may be 
viewed by typing ? (question mark followed by <RETURN>).  The HELP command 
will give you a one line description of each of them.

3.0 Commands.
	The following list describes each of the commands, and gives hints 
about their use where appropriate.  The minimun abbreviation of the command 
is given in brackets after the command name.

	The @ (at-sign) command tells REV to execute the current file as a 
	DCL command procedure.  There is no abbreviation for this command.

	Appends the current file to another. REV will prompt you for the name
	of the other file.

	Clears the screen and reprompts at the same current file.  The 
	prompt is displayed at the top of the screen.

	Copies the current file to a new file. REV will prompt you for the 
	new name.

	Deletes the current file. (TOPS-20 users note that VMS does not 
	have an UNDELETE facility as standard).

	If the current file is a subdirectory, REV does a directory listing 
	of it.  If the current file is not a subdirectory, the listing is of 
	the parent directory (i.e. the one you are currently REViewing).  
	In both cases the listing is of all files.

	Dumps the current file in the default DUMP format.

	Edits the current file with EDT.  REV needs to be able to find an 
	EDT initialisation file in your default login directory, and 
	produces no journal file.  If you QUIT from the edit, REV prompts 
	you at the same file again; if you EXIT, REV steps on to the next

	If the current file is a subdirectory, this does a REV *.* on that
	subdirectory.  When you exit from the subdirectory, REV prompts you
	at the subdirectory file again.

	Exits from REV.  Typing control-Z has the same effect.

	This does a full directory of the current file.

	Types out a one line description of each command.

	Disables the current USP.

	Sets the UIC of the current file to that of its directory.

	Prints the current file on SYS$PRINT.

	Displays, and optionally changes the protection of the current 
	file.  REV will prompt you to "Enter new protection code"; if you
	just press <RETURN>, the protection remains unchanged.  If you wish 
	to change it, enter the code in the same syntax as for the SET
	PROTECTION= command, but if you specify more than one class of 
	users, do not enclose the list in () brackets.

	This gets you a DCL command processor operating within REV.  To 
	return to REV type POP (or PO).  Commands entered while PUSHed
	are executed in the process which is running REV.

	Renames the current file.  REV will prompt you for the new name.

	Runs the current .EXE file.  If the current file's type is not .EXE 
	REV will not attempt to run it.

	Searches the current file for a text string.  REV will prompt you 
	for the string to search for.

	Enables a USP.  The filespec of the current USP (if any) is 
	reported, and you are prompted for a new one.  If a new filespec is 
	not entered, the current one is enabled.

	Spawns a subprocess and attaches your terminal to it.  To return to 
	REV type RETURN (abbr. RET).  If you exit from the subprocess by 
	any other means, the subprocess may not be killed off correctly.
	Commands executed while SPAWNed are executed in a process 
	independant of that running REV.

	Stores the device, directory, and filename of the current file into
	the file REV.LST in your SYS$LOGIN directory.  If the file does not
	exist it is created.  If the file does exist the current filespec is 
	appended into it.

	Types out the current file on your terminal.

	Two control characters are recognised by REV.  Control-Y interrupts 
the currently executing command (except PUSH) and returns you to the prompt.
Control-Z has the same effect as the EXIT command when you are at the prompt.

3.1 Deleting a subdirectory

	REV can make this a simple operation when there are files still 
existing in the subdirectory.  The procedure is to ENTER the subdirectory,
COPY and then DELETE the files you want to keep from it, DELETE those you 
don't want.  When you get to the end of the subdirectory REV returns you to 
looking at the subdirectory file again.  Now change the PROTECTion to O:D, 
and DELETE the subdirectory file.

4.0 The User Selection Procedure facility.

	REV may make use of an optional User Selection Procedure (USP).
The USP decides whether a particular file is to be REViewed or not, by any
method the user wishes.

	Each time REV steps on to the next file, it calls the USP, passing 
the filespec, including device and directory, as parameter P1.  The USP
determines whether the file should be REViewed or not, and sets up the global 
symbol SELECTED with the value TRUE if the file should be REViewed, or FALSE 
if not.  

	The presence of a USP may signalled to REV by the global symbol 
REV_SELECT.  If this is defined before invoking REV, it is assumed it to 
contain the filespec of the USP.  The filespec must include the file type.

	There are two commands which affect USPs while REV is running.
SELECT enables either the current, or a new USP.  The USP will be invoked 
for the next file REV steps to.  NOSELECT disables the current USP.  The 
USP facility is enabled when REV is invoked, thus if the global symbol 
REV_SELECT is defined, the USP it points to will be used to test all files
in the group being REViewed.  If the symbol is not defined the USP facility 
is disabled, to reduce the overhead, but may be enabled by SELECT.

	The file REVSEL.COM is an example USP to select files of 5 or more 
blocks.  To watch what it does type :-

	$ REV

Note that if REV is invoked by :-

	$ REV *.MAR

only .MAR files of 5 or more blocks will be REViewed.

	The REVSEL example reports the names of files it decides not to 
REView.  This is included for demonstration only, and is not necessary in 
user applications.

	An alternative method of using the example USP is :-

	$ REV *.COM
	  REV v3.4
	FROBNITZ.COM  2  27-JUN-1984 12:34:56.7 > SELECT
	Select file is not set up, enter new filespec or RETURN
	New filespec : REVSEL.COM
	FROBNITZ.COM  2  27-JUN-1984 12:34:56.7 > 

The USP will be used to test the next file that is stepped to after a 

5.0 Installation.
	REV requires no special installation.  The files required are :-

		REV.COM		the one that does the work
		REV.DOC		this description of REV
		REVSEL.COM	a sample USP

The files should be placed wherever is appropriate, e.g. SYS$SYSTEM, with 
at least execute access to the world.