."\ replace.1
.TH REPLACE P " V1.1 21 September 89 for Prog. V1.4" "Julian Stacey" "Julian Stacey, Vector Systems Ltd"
.\" A4 the cludgy way.
.pl 29.6c
.UC 4
.SH NAME
replace \- Replace strings in text or binary files.
.SH SYNTAX
.B replace
-oOut_string [-iIn_string] [-fFill_ch] [-eExtra_length] [-v] [-b/t] [-c] [-N/nOccurences] [-s] file[s]
.SH SUMMARY
A bit like a simple Unix `sed' functionally (but not in syntax),
but
.I replace
is safe to use on both text and binary files (according to option switch).

.I Replace
replaces all occurrences of a string in a file
with an alternate string (which is assumed of zero size if unspecified),
if the binary option is enabled, the replaced string is automatically blank padded, or truncated as appropriate.
Checksums on binary files can be preserved.
.SH DESCRIPTION
.I Replace
is not a standard Unix command, it is unique to VSL systems with the Ournix overlay.

Typical use is to update copyright stamps,
correct spelling mistakes, or change the human/natural language
in executable files,
without needing to recompile the corrected files.
.I replace
also offers for Msdos users the Unix `Sed' like facility of being able
to make wholesale string substitutions,
on all text files in an Msdos directory.

.I Replace
does not prevent the operating system automatically updating
the file time stamp.
.I Replace
makes no special provision regarding file access modes.
.I Replace can allow for msdos executable checksum maintenance.

.SH PARAMETERS
Parameters must precede file names.
Both Msdos Command.com and Unix Csh support the use of double quotes("),
allowing strings with spaces to be passed to
.I replace
as a single parameter (for instance: -o"Winchester disc" -i"Hard disk").
Parameters available include :-
.TP
.B \-o
Specify string to be taken out of file.
This parameter is mandatory, it must be used.
.TP
.B \-i
Specify string to be inserted in to file.
This parameter is optional.
If no string is specified, nothing will be inserted to replace extracted -o
strings (unless -b is used, in which case the gap will be blank filled).
The -i string length will be truncated if necessary to ensure it is not
greater than the -o string length.
.TP
.B \-fFill_char
Fill character [space]
The fill/padding character is space by default, but can be changed
by this option (note this option takes the character `straight',
not as a hex or octal value).
.TP
.B \-eExtra
Extra bytes:
each time a -o string is recognised in the file(s),
swallow an extra number of bytes after the end,
converting them to blanks if in binary mode.
.br
The space created by removing these extra bytes is not available for use by -i
strings (thus this is not a way of getting a -i string
to be bigger than a -o string).
.TP
.B \-v [OFF]
Turn verbose mode on, herald each file before starting work on it.
.TP
.B \-t
Text file type (default option).
No padding or truncation:
Allow the output file to vary in size from the input, replacement strings
will not be blank padded or truncated.
.TP
.B \-b
Binary file type.
Automatic padding or truncation of strings as appropriate.
Strings in files do not need to be null terminated,
.I replace
will not change whether or not they are null terminated.
Nulls will remain if present in the original, & not be present if not present
in the original.
File sizes remains unchanged, all bytes retain the same
position in files.
.TP
.B \-c
Checksum:
Treat the file as an msdos.exe file, display the original msdos checksum,
and patch checksum to allow for any text changes.
Use of this option automatically incorporates -b actions.
Checksum is calculated on all bytes after byte number
0x1B (1st byte is byte number 0)
Replace action is done only beyond 0x1B.
Support has not yet been extended to include preserving checksums in
Unix executables.
.TP
.B \-nNumber or -Nnumber [-1]
Allow up to a certain number of occurences to do.
The special (default) value of -1 means "dont care - none or many",
0 means none (this should only be useful if invoked as -N), 1 means 1,
2 means 2, etc.
-n5 means do up to 5 occurences, if opportunity arises.
-N5 means do exactly 5 occurences,
and if you fail to do exactly 5, complain and exit with an error code.
.TP
.B \-s
Use site specific local default values for -o and -i.
This `shorthand' option is only available internally within VSL Ltd for
developers, all the functionality it provides can be obtained by use
of other options such as -o and -i.
Use of this option automatically incorporates -c actions.

Note
.br
The functionality provided within this command is serviced by a custom built
library procedure, also used by
.I expire(1).
.SH RESTRICTIONS
.I Replace
does not detect binary or text file type according to
file name extension/suffix,
you the user must must specify binary if necessary.
.br
.I Replace
used on Unix libraries may cause a problem,
as it does not recompute checksums.
.br
There is NO limit to the length of the -i & -o parameters,
except that imposed by the command interpreter passing arguments to
.I replace.
Any character (except the null terminator) passed to
.I replace
is valid for the -o and -i arguments.
The only restriction being which unusual/special characters
your command interpreter may refuse to pass in.
.SH EXAMPLE
Example 1
.in +5
A binary file called data, including the byte sequence:
.ti +5
11111_____33333
.br
Will be converted by this command:
.ti +5
.I replace
-b -o____ -i_222 data
.br
To afterwards contain:
.ti +5
11111_222_33333
.in -5
Example 2
.in +5
.I replace
-b
-o"User Eror: RTFM !"
-i"Syntax Error: Please read User Manual." 
*.exe
.in -5
Explanation 2
.in +5
Fix all Msdos.exe executables that have a standard but undesirable
error message from an illiterate rude programmer!.
.in -5
Example 3
.in +5
.I Replace
-o"Mrs Margaret Thatcher" 
-i"Mr John Major"
government_files/*
.in -5
Explanation 3
.in +5
Change names after an election.
.in -5
.SH EXIT CODE
0 if no error has occurred, else 1 if an error occurs.
(remaining files are not processed, once an error occurs).
.SH HOST OP SYSTEM
This utility runs on both Msdos 3.2 & Unix UCB BSD 4.2.
.SH COPYRIGHT
Program Copyright Julian H. Stacey, Munich, 27th July 1989.
.br
Manual Copyright Julian H. Stacey, Munich, 28th July 1989.
.so author.jhs
.BUGS
None known, but not extensively tested as at 29th July 89 -
use with care.
.SH ENHANCEMENTS LATER
Pipe IO (like Sed).
.SH FILES
Unix:	replace.XXXXXX
.br
Msdos:	/tmp/reXXXXXX
.br
.ti +20
XXXXXX being used as per mktemp(3).
.\" .SH SEE ALSO
expire(1).
.\ End of file